sub-agents-mcp 0.1.4 → 0.2.0

package/dist/session/SessionManager.js

@@ -0,0 +1,410 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+const node_fs_1 = require("node:fs");
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+/**
+ * Session manager for handling session data persistence.
+ *
+ * Manages session data storage, retrieval, and cleanup operations.
+ * Ensures secure file handling with directory traversal prevention.
+ */
+class SessionManager {
+    /**
+     * Creates a new SessionManager instance.
+     *
+     * Initializes the session directory synchronously to ensure it exists
+     * before any operations are performed.
+     *
+     * @param config - Session configuration containing directory path and retention settings
+     */
+    constructor(config) {
+        this.config = config;
+        this.initializeSessionDirectory();
+    }
+    /**
+     * Initializes the session directory by creating it if it doesn't exist.
+     * Uses synchronous file operations to ensure directory exists before returning.
+     *
+     * @private
+     * @throws {Error} If directory creation fails
+     */
+    initializeSessionDirectory() {
+        try {
+            (0, node_fs_1.mkdirSync)(this.config.sessionDir, { recursive: true });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`Failed to create session directory at ${this.config.sessionDir}:`, errorMessage);
+            throw new Error(`Session directory initialization failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Validates a session ID to ensure it only contains allowed characters.
+     * Prevents directory traversal attacks by rejecting IDs with path manipulation characters.
+     *
+     * Session IDs must:
+     * - Not be empty
+     * - Contain only alphanumeric characters, hyphens (-), and underscores (_)
+     * - Not contain path traversal sequences (../, ./, etc.)
+     *
+     * @param sessionId - The session ID to validate
+     * @throws {Error} If the session ID contains invalid characters or is empty
+     */
+    validateSessionId(sessionId) {
+        if (!sessionId || sessionId.length === 0) {
+            throw new Error('Invalid session ID: Session ID cannot be empty');
+        }
+        // Only allow alphanumeric characters, hyphens, and underscores
+        const validPattern = /^[a-zA-Z0-9_-]+$/;
+        if (!validPattern.test(sessionId)) {
+            throw new Error(`Invalid session ID: "${sessionId}" contains invalid characters. Only alphanumeric characters, hyphens (-), and underscores (_) are allowed`);
+        }
+    }
+    /**
+     * Builds a file path for a session file following the naming convention:
+     * [session_id]_[agent_type].json
+     *
+     * Security measures:
+     * - Validates session ID before processing
+     * - Uses path.basename to strip directory components
+     * - Verifies final path is within session directory
+     *
+     * @param sessionId - The session identifier (validated for security)
+     * @param agentType - The type of agent (e.g., 'rule-advisor', 'quality-fixer')
+     * @returns The full file path for the session file
+     * @throws {Error} If the session ID is invalid or if path traversal is detected
+     */
+    buildFilePath(sessionId, agentType) {
+        // Validate session ID to prevent directory traversal
+        this.validateSessionId(sessionId);
+        // Build filename following the naming convention
+        const fileName = `${sessionId}_${agentType}.json`;
+        // Strip any directory components for additional security
+        const safeFileName = path.basename(fileName);
+        // Join with session directory
+        const filePath = path.join(this.config.sessionDir, safeFileName);
+        // Verify the resolved path stays within the session directory
+        const normalizedPath = path.normalize(filePath);
+        const normalizedSessionDir = path.normalize(this.config.sessionDir);
+        if (!normalizedPath.startsWith(normalizedSessionDir)) {
+            throw new Error(`Invalid file path: Attempted directory traversal detected. Expected path within "${normalizedSessionDir}", got "${normalizedPath}"`);
+        }
+        return filePath;
+    }
+    /**
+     * Saves session data to a JSON file.
+     *
+     * If a session file already exists, the new request-response pair is appended
+     * to the existing history. Otherwise, a new session file is created.
+     *
+     * Error handling follows the error isolation principle:
+     * - Errors are logged but not thrown
+     * - The main execution flow continues even if session save fails
+     *
+     * Security features:
+     * - Session ID validation prevents directory traversal
+     * - File permissions are set to 0o600 (owner read/write only)
+     * - All file paths are verified to stay within session directory
+     *
+     * @param sessionId - The session identifier (alphanumeric, hyphens, underscores only)
+     * @param request - The request object containing agent, prompt, and optional parameters
+     * @param response - The response object containing stdout, stderr, exitCode, and executionTime
+     *
+     * @example
+     * await sessionManager.saveSession(
+     *   'session-001',
+     *   { agent: 'rule-advisor', prompt: 'Analyze code' },
+     *   { stdout: 'Analysis complete', stderr: '', exitCode: 0, executionTime: 100 }
+     * )
+     */
+    async saveSession(sessionId, request, response) {
+        try {
+            // Validate session ID to prevent directory traversal
+            this.validateSessionId(sessionId);
+            // Create session entry with current timestamp
+            const sessionEntry = {
+                timestamp: new Date(),
+                request,
+                response,
+            };
+            // Build or update session data
+            const sessionData = await this.buildSessionData(sessionId, request.agent, sessionEntry);
+            // Build file path (same file for same session_id + agent_type)
+            const filePath = this.buildFilePath(sessionId, request.agent);
+            // Serialize to JSON with pretty printing
+            const jsonContent = JSON.stringify(sessionData, null, 2);
+            // Write to file with restrictive permissions
+            await fs.writeFile(filePath, jsonContent, { mode: 0o600 });
+        }
+        catch (error) {
+            // Log error but do not throw - error isolation principle
+            this.logSaveError(sessionId, request.agent, error);
+        }
+    }
+    /**
+     * Builds session data by either creating a new session or appending to an existing one.
+     *
+     * @param sessionId - The session identifier
+     * @param agentType - The agent type
+     * @param sessionEntry - The new session entry to add
+     * @returns Complete session data ready to be saved
+     */
+    async buildSessionData(sessionId, agentType, sessionEntry) {
+        const existingSession = await this.loadExistingSession(sessionId, agentType);
+        if (existingSession) {
+            // Append to existing session history
+            return {
+                ...existingSession,
+                history: [...existingSession.history, sessionEntry],
+                lastUpdatedAt: new Date(),
+            };
+        }
+        // Create new session with initial entry
+        return {
+            sessionId,
+            agentType,
+            history: [sessionEntry],
+            createdAt: new Date(),
+            lastUpdatedAt: new Date(),
+        };
+    }
+    /**
+     * Logs structured error information when session save fails.
+     *
+     * @param sessionId - The session identifier
+     * @param agentType - The agent type
+     * @param error - The error that occurred
+     */
+    logSaveError(sessionId, agentType, error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error('Failed to save session:', {
+            sessionId,
+            agentType,
+            error: errorMessage,
+        });
+    }
+    /**
+     * Loads a session by session ID and agent type.
+     *
+     * Searches for the most recent session file matching the session ID and agent type.
+     * If multiple files exist with the same session ID and agent type, returns the one with the latest timestamp.
+     *
+     * **CRITICAL**: Sub-agent isolation is enforced - sessions are isolated by agent type.
+     * Same session_id with different agent_type will return different sessions.
+     *
+     * Error handling follows the error isolation principle:
+     * - Returns null if session file does not exist
+     * - Returns null if JSON parsing fails
+     * - Errors are logged but not thrown
+     *
+     * @param sessionId - The session identifier (alphanumeric, hyphens, underscores only)
+     * @param agentType - The agent type to filter sessions (e.g., 'rule-advisor', 'task-executor')
+     * @returns The session data if found, null otherwise
+     *
+     * @example
+     * const session = await sessionManager.loadSession('session-001', 'rule-advisor')
+     * if (session) {
+     *   console.log(`Loaded session with ${session.history.length} entries`)
+     * }
+     */
+    async loadSession(sessionId, agentType) {
+        try {
+            // Validate session ID to prevent directory traversal
+            this.validateSessionId(sessionId);
+            // Build expected file path
+            // File naming convention: [session_id]_[agent_type].json
+            const filePath = this.buildFilePath(sessionId, agentType);
+            // Check if file exists
+            try {
+                await fs.access(filePath);
+            }
+            catch {
+                // File does not exist
+                return null;
+            }
+            const fileContent = await fs.readFile(filePath, 'utf-8');
+            const sessionData = JSON.parse(fileContent);
+            // Convert date strings back to Date objects
+            return {
+                ...sessionData,
+                createdAt: new Date(sessionData.createdAt),
+                lastUpdatedAt: new Date(sessionData.lastUpdatedAt),
+                history: sessionData.history.map((entry) => ({
+                    ...entry,
+                    timestamp: new Date(entry.timestamp),
+                })),
+            };
+        }
+        catch (error) {
+            // Log error but return null - error isolation principle
+            this.logLoadError(sessionId, error);
+            return null;
+        }
+    }
+    /**
+     * Loads an existing session file if it exists.
+     *
+     * Searches for the most recent session file matching the session ID and agent type.
+     *
+     * @param sessionId - The session identifier
+     * @param agentType - The agent type
+     * @returns The session data if found, null otherwise
+     */
+    async loadExistingSession(sessionId, agentType) {
+        try {
+            // Build expected file path
+            // File naming convention: [session_id]_[agent_type].json
+            const filePath = this.buildFilePath(sessionId, agentType);
+            // Check if file exists
+            try {
+                await fs.access(filePath);
+            }
+            catch {
+                // File does not exist
+                return null;
+            }
+            const fileContent = await fs.readFile(filePath, 'utf-8');
+            const sessionData = JSON.parse(fileContent);
+            // Convert date strings back to Date objects
+            return {
+                ...sessionData,
+                createdAt: new Date(sessionData.createdAt),
+                lastUpdatedAt: new Date(sessionData.lastUpdatedAt),
+                history: sessionData.history.map((entry) => ({
+                    ...entry,
+                    timestamp: new Date(entry.timestamp),
+                })),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Logs structured error information when session load fails.
+     *
+     * @param sessionId - The session identifier
+     * @param error - The error that occurred
+     */
+    logLoadError(sessionId, error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error('Failed to load session:', {
+            sessionId,
+            error: errorMessage,
+        });
+    }
+    /**
+     * Cleans up old session files based on retention period.
+     *
+     * Deletes session files older than the configured retention period (default 7 days).
+     * This is a best-effort operation - errors during deletion are logged but not thrown.
+     *
+     * Error handling follows the error isolation principle:
+     * - Individual file deletion failures do not stop the cleanup process
+     * - All errors are logged for debugging purposes
+     * - The method completes successfully even if some files cannot be deleted
+     *
+     * @example
+     * // Cleanup old sessions (runs silently, logs errors only)
+     * await sessionManager.cleanupOldSessions()
+     */
+    async cleanupOldSessions() {
+        try {
+            // List all files in the session directory
+            const files = await fs.readdir(this.config.sessionDir);
+            // Calculate cutoff time based on retention period
+            const retentionMs = this.config.retentionDays * 24 * 60 * 60 * 1000;
+            const cutoffTime = Date.now() - retentionMs;
+            let deletedCount = 0;
+            const deletedFiles = [];
+            // Process each file
+            for (const file of files) {
+                // Skip non-JSON files
+                if (!file.endsWith('.json')) {
+                    continue;
+                }
+                const filePath = path.join(this.config.sessionDir, file);
+                try {
+                    // Get file stats to check modification time
+                    const stats = await fs.stat(filePath);
+                    // Check if file is older than retention period
+                    if (stats.mtimeMs < cutoffTime) {
+                        try {
+                            // Delete the old file
+                            await fs.unlink(filePath);
+                            deletedCount++;
+                            deletedFiles.push(file);
+                        }
+                        catch (deleteError) {
+                            // Log individual file deletion error but continue
+                            const errorMessage = deleteError instanceof Error ? deleteError.message : String(deleteError);
+                            console.error(`Failed to delete old session file: ${file}`, {
+                                file,
+                                error: errorMessage,
+                            });
+                        }
+                    }
+                }
+                catch (statError) {
+                    // Log stat error but continue with next file
+                    const errorMessage = statError instanceof Error ? statError.message : String(statError);
+                    console.error(`Failed to stat session file: ${file}`, {
+                        file,
+                        error: errorMessage,
+                    });
+                }
+            }
+            // Log cleanup summary
+            if (deletedCount > 0) {
+                console.log('Cleaned up old session files:', {
+                    deletedCount,
+                    deletedFiles,
+                });
+            }
+        }
+        catch (error) {
+            // Log error but do not throw - error isolation principle
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error('Failed to cleanup old sessions:', {
+                error: errorMessage,
+            });
+        }
+    }
+}
+exports.SessionManager = SessionManager;
+//# sourceMappingURL=SessionManager.js.map

package/dist/session/SessionManager.js.map

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

package/dist/session/ToonConverter.d.ts

@@ -0,0 +1,172 @@
+/**
+ * TOON (Token Optimized Object Notation) converter utility.
+ *
+ * Converts JSON data to TOON format to reduce token consumption by 30-60%.
+ *
+ * Key optimizations:
+ * - Shortened key names (sessionId → sid, timestamp → ts, etc.)
+ * - Compact timestamp format (removes separators: 20250121 120000)
+ * - Filters out empty strings and empty arrays
+ * - Inline object representation {key:value,key2:value2}
+ * - Array format [count,]{item1,item2}
+ *
+ * @example
+ * ```typescript
+ * const sessionData = {
+ *   sessionId: 'abc123',
+ *   agentType: 'rule-advisor',
+ *   history: [...],
+ *   createdAt: new Date('2025-01-21T12:00:00Z'),
+ *   lastUpdatedAt: new Date('2025-01-21T12:00:00Z')
+ * }
+ * const toonStr = ToonConverter.convertToToon(sessionData)
+ * // Output: sid:abc123,agt:rule-advisor,h:[1,]{...},cat:20250121 120000,uat:20250121 120000
+ * ```
+ */
+export declare class ToonConverter {
+    /**
+     * Converts JSON-compatible data to TOON format.
+     *
+     * TOON format features:
+     * - Removes quotes from keys
+     * - Uses compact array notation: [length,] { items }
+     * - Reduces unnecessary brackets and commas
+     * - Maintains data structure and readability
+     *
+     * @param jsonData - JSON-compatible data to convert
+     * @returns TOON-formatted string
+     *
+     * @example
+     * ```typescript
+     * const data = { sessionId: 'abc123', agentType: 'rule-advisor' }
+     * const toon = ToonConverter.convertToToon(data)
+     * // Returns: "sessionId: abc123\nagentType: rule-advisor"
+     * ```
+     */
+    static convertToToon(jsonData: unknown): string;
+    /**
+     * Map of common long keys to short keys for token reduction.
+     * @private
+     */
+    private static readonly KEY_MAP;
+    /**
+     * Recursively converts a value to TOON format string.
+     *
+     * @param value - Value to convert
+     * @param depth - Current nesting depth for indentation
+     * @returns TOON-formatted string
+     * @private
+     */
+    private static toToonString;
+    /**
+     * Converts an object to compact TOON format (for array items).
+     *
+     * @param value - Object to convert
+     * @returns Compact TOON string
+     * @private
+     */
+    private static toToonObjectCompact;
+    /**
+     * Formats a Date object to compact timestamp format.
+     *
+     * Converts ISO 8601 timestamp to compact format:
+     * - Input: 2025-01-21T12:00:00.000Z
+     * - Output: 20250121 120000
+     *
+     * This reduces token count by removing separators and milliseconds.
+     *
+     * @param date - Date object to format
+     * @returns Compact timestamp string
+     * @private
+     */
+    private static formatCompactTimestamp;
+    /**
+     * Checks if a string value needs to be quoted in TOON format.
+     *
+     * Strings are quoted if they contain:
+     * - Spaces
+     * - Special characters (except hyphen and underscore)
+     * - Start with a number
+     * - Reserved keywords (null, undefined, true, false)
+     *
+     * @param value - String value to check
+     * @returns True if the string needs quotes
+     * @private
+     */
+    private static needsQuotes;
+    /**
+     * Converts TOON format string back to JSON-compatible data.
+     *
+     * This method reverses the convertToToon operation, restoring the original data structure.
+     * - Expands short keys back to full keys
+     * - Parses compact timestamps back to Date objects
+     * - Reconstructs arrays and objects from TOON notation
+     *
+     * @param toonString - TOON-formatted string to convert
+     * @returns JSON-compatible data
+     *
+     * @example
+     * ```typescript
+     * const toonStr = "sid:abc123,agt:rule-advisor,h:[1,]{ts:20250121 120000},cat:20250121 120000"
+     * const data = ToonConverter.convertToJson(toonStr)
+     * // Returns: { sessionId: 'abc123', agentType: 'rule-advisor', history: [...], ... }
+     * ```
+     */
+    static convertToJson(toonString: string): unknown;
+    /**
+     * Reverse map from short keys to original keys.
+     * @private
+     */
+    private static readonly REVERSE_KEY_MAP;
+    /**
+     * Parses a TOON format string into a JSON-compatible value.
+     *
+     * @param input - TOON string to parse
+     * @returns Parsed value
+     * @private
+     */
+    private static parseToonString;
+    /**
+     * Parses a compact timestamp string back to Date object.
+     *
+     * Converts compact format to ISO 8601:
+     * - Input: 20250121 120000
+     * - Output: Date('2025-01-21T12:00:00.000Z')
+     *
+     * @param timestamp - Compact timestamp string
+     * @returns Date object
+     * @private
+     */
+    private static parseCompactTimestamp;
+    /**
+     * Parses TOON array notation.
+     *
+     * Format: [length,]item1,item2,item3
+     * or [length,]{item1},{item2}
+     *
+     * @param input - TOON array string
+     * @returns Parsed array
+     * @private
+     */
+    private static parseArray;
+    /**
+     * Parses TOON object notation.
+     *
+     * Format: key1:value1,key2:value2
+     * or {key1:value1,key2:value2}
+     *
+     * @param input - TOON object string
+     * @returns Parsed object
+     * @private
+     */
+    private static parseObject;
+    /**
+     * Parses a key:value pair and adds it to the result object.
+     *
+     * @param pair - Key:value pair string
+     * @param result - Result object to add to
+     * @private
+     */
+    private static parseKeyValue;
+}
+//# sourceMappingURL=ToonConverter.d.ts.map

package/dist/session/ToonConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToonConverter.d.ts","sourceRoot":"","sources":["../../src/session/ToonConverter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,qBAAa,aAAa;IACxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM;IAe/C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAa9B;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAiE3B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAmDlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IASrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAkB1B;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAgBjD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAEtC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAuD9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAkBpC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAqEzB;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAkG1B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;CA2C7B"}