@skillsmith/core 0.4.0 → 0.4.2

package/dist/src/services/TaskRunner.js

@@ -0,0 +1,423 @@
+/**
+ * SMI-1662: TaskRunner - Background Task Timeout Management
+ *
+ * Provides configurable timeout enforcement for background Task agents.
+ * Addresses orphaned process memory leaks identified in incident 2026-01-22.
+ *
+ * Features:
+ * - Configurable timeout via TASK_TIMEOUT_MS environment variable
+ * - Default timeout: 10 minutes (600000ms)
+ * - Warning at 80% of timeout limit
+ * - Graceful shutdown: SIGTERM -> wait 5s -> SIGKILL
+ * - Task registry for tracking running background tasks
+ *
+ * @example
+ * ```typescript
+ * const runner = new TaskRunner({ timeoutMs: 300000 }) // 5 minute timeout
+ * const taskId = runner.register(childProcess.pid, 'SMI-1660 implementation')
+ *
+ * // When task completes
+ * runner.complete(taskId)
+ *
+ * // Cleanup orphaned tasks
+ * await runner.cleanupOrphaned()
+ * ```
+ */
+import { randomUUID } from 'crypto';
+import { createLogger } from '../utils/logger.js';
+/**
+ * Default timeout: 10 minutes (600000ms)
+ */
+export const DEFAULT_TASK_TIMEOUT_MS = 600000;
+/**
+ * Grace period before SIGKILL after SIGTERM: 5 seconds
+ */
+export const SIGKILL_GRACE_PERIOD_MS = 5000;
+/**
+ * Warning threshold: 80% of timeout
+ */
+export const WARNING_THRESHOLD_RATIO = 0.8;
+/**
+ * TaskRunner manages background task lifecycles with timeout enforcement.
+ *
+ * Solves the orphaned process problem by:
+ * 1. Tracking all background tasks in a registry
+ * 2. Enforcing configurable timeouts
+ * 3. Graceful shutdown with SIGTERM -> SIGKILL escalation
+ * 4. Logging all timeout events for debugging
+ */
+export class TaskRunner {
+    config;
+    logger;
+    tasks = new Map();
+    timers = new Map();
+    warningTimers = new Map();
+    onTimeout;
+    onWarning;
+    constructor(config = {}) {
+        const envTimeout = process.env.TASK_TIMEOUT_MS
+            ? parseInt(process.env.TASK_TIMEOUT_MS, 10)
+            : undefined;
+        this.config = {
+            timeoutMs: config.timeoutMs ?? envTimeout ?? DEFAULT_TASK_TIMEOUT_MS,
+            debug: config.debug ?? process.env.DEBUG === 'true',
+        };
+        this.logger = config.logger ?? createLogger('TaskRunner');
+        this.onTimeout = config.onTimeout;
+        this.onWarning = config.onWarning;
+        if (this.config.debug) {
+            this.logger.debug('TaskRunner initialized', {
+                timeoutMs: this.config.timeoutMs,
+                warningThresholdMs: Math.floor(this.config.timeoutMs * WARNING_THRESHOLD_RATIO),
+            });
+        }
+    }
+    /**
+     * Register a new background task for monitoring
+     *
+     * @param pid - Process ID of the background task
+     * @param description - Human-readable description
+     * @returns Task ID for tracking
+     */
+    register(pid, description) {
+        const id = randomUUID();
+        const now = Date.now();
+        const task = {
+            id,
+            pid,
+            description,
+            startedAt: now,
+            status: 'running',
+            warningIssued: false,
+        };
+        this.tasks.set(id, task);
+        // Set warning timer at 80% of timeout
+        const warningMs = Math.floor(this.config.timeoutMs * WARNING_THRESHOLD_RATIO);
+        const warningTimer = setTimeout(() => {
+            this.issueWarning(id);
+        }, warningMs);
+        this.warningTimers.set(id, warningTimer);
+        // Set timeout timer
+        const timeoutTimer = setTimeout(() => {
+            void this.handleTimeout(id);
+        }, this.config.timeoutMs);
+        this.timers.set(id, timeoutTimer);
+        if (this.config.debug) {
+            this.logger.debug('Task registered', {
+                taskId: id,
+                pid,
+                description,
+                timeoutMs: this.config.timeoutMs,
+            });
+        }
+        return id;
+    }
+    /**
+     * Mark a task as completed successfully
+     *
+     * @param taskId - Task ID to complete
+     */
+    complete(taskId) {
+        this.finishTask(taskId, 'completed');
+    }
+    /**
+     * Mark a task as failed
+     *
+     * @param taskId - Task ID that failed
+     * @param error - Error message or Error object
+     */
+    fail(taskId, error) {
+        const task = this.tasks.get(taskId);
+        if (task) {
+            task.error = error instanceof Error ? error.message : error;
+        }
+        this.finishTask(taskId, 'failed');
+    }
+    /**
+     * Get a tracked task by ID
+     *
+     * @param taskId - Task ID to retrieve
+     * @returns The tracked task or undefined
+     */
+    getTask(taskId) {
+        return this.tasks.get(taskId);
+    }
+    /**
+     * Get all tasks with a specific status
+     *
+     * @param status - Status to filter by (optional, returns all if not specified)
+     * @returns Array of matching tasks
+     */
+    getTasks(status) {
+        const tasks = Array.from(this.tasks.values());
+        return status ? tasks.filter((t) => t.status === status) : tasks;
+    }
+    /**
+     * Get statistics about tracked tasks
+     */
+    getStats() {
+        const tasks = Array.from(this.tasks.values());
+        return {
+            total: tasks.length,
+            running: tasks.filter((t) => t.status === 'running').length,
+            completed: tasks.filter((t) => t.status === 'completed').length,
+            failed: tasks.filter((t) => t.status === 'failed').length,
+            timeout: tasks.filter((t) => t.status === 'timeout').length,
+            killed: tasks.filter((t) => t.status === 'killed').length,
+        };
+    }
+    /**
+     * Clean up completed/failed/timeout tasks older than specified age
+     *
+     * @param maxAgeMs - Maximum age in milliseconds (default: 1 hour)
+     * @returns Number of tasks cleaned up
+     */
+    cleanup(maxAgeMs = 3600000) {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, task] of this.tasks.entries()) {
+            if (task.status !== 'running' && task.endedAt && now - task.endedAt > maxAgeMs) {
+                this.tasks.delete(id);
+                cleaned++;
+            }
+        }
+        if (this.config.debug && cleaned > 0) {
+            this.logger.debug('Cleaned up old tasks', { count: cleaned, maxAgeMs });
+        }
+        return cleaned;
+    }
+    /**
+     * Clean up all orphaned running tasks that have exceeded timeout
+     * This can be called externally to force cleanup
+     *
+     * @returns Cleanup result with details
+     */
+    async cleanupOrphaned() {
+        const now = Date.now();
+        const result = {
+            cleaned: 0,
+            taskIds: [],
+            errors: [],
+        };
+        for (const [id, task] of this.tasks.entries()) {
+            if (task.status === 'running' && now - task.startedAt > this.config.timeoutMs) {
+                try {
+                    await this.killProcess(task.pid);
+                    this.finishTask(id, 'killed');
+                    result.cleaned++;
+                    result.taskIds.push(id);
+                }
+                catch (error) {
+                    result.errors.push({
+                        taskId: id,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        if (result.cleaned > 0) {
+            this.logger.warn('Cleaned up orphaned tasks', {
+                count: result.cleaned,
+                taskIds: result.taskIds,
+                errors: result.errors.length,
+            });
+        }
+        return result;
+    }
+    /**
+     * Dispose of the TaskRunner and clean up all timers
+     */
+    dispose() {
+        // Clear all timers
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        for (const timer of this.warningTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.warningTimers.clear();
+        if (this.config.debug) {
+            this.logger.debug('TaskRunner disposed', { taskCount: this.tasks.size });
+        }
+    }
+    /**
+     * Get the configured timeout in milliseconds
+     */
+    getTimeoutMs() {
+        return this.config.timeoutMs;
+    }
+    /**
+     * Issue a warning that task is approaching timeout
+     */
+    issueWarning(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task || task.status !== 'running') {
+            return;
+        }
+        const remainingMs = this.config.timeoutMs - (Date.now() - task.startedAt);
+        task.warningIssued = true;
+        this.logger.warn('Task approaching timeout', {
+            taskId,
+            pid: task.pid,
+            description: task.description,
+            elapsedMs: Date.now() - task.startedAt,
+            remainingMs,
+            timeoutMs: this.config.timeoutMs,
+        });
+        this.onWarning?.(task, remainingMs);
+    }
+    /**
+     * Handle a task timeout
+     */
+    async handleTimeout(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task || task.status !== 'running') {
+            return;
+        }
+        const durationMs = Date.now() - task.startedAt;
+        this.logger.error('Task timed out', undefined, {
+            taskId,
+            pid: task.pid,
+            description: task.description,
+            durationMs,
+            timeoutMs: this.config.timeoutMs,
+        });
+        // Attempt graceful shutdown
+        try {
+            await this.gracefulShutdown(task.pid);
+            this.finishTask(taskId, 'timeout');
+        }
+        catch (error) {
+            this.logger.error('Failed to terminate timed out task', error instanceof Error ? error : new Error(String(error)), { taskId, pid: task.pid });
+            this.finishTask(taskId, 'timeout');
+        }
+        this.onTimeout?.(task);
+    }
+    /**
+     * Gracefully shutdown a process: SIGTERM -> wait -> SIGKILL
+     */
+    async gracefulShutdown(pid) {
+        // First, send SIGTERM for graceful shutdown
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch (error) {
+            // Process might already be dead
+            if (error.code === 'ESRCH') {
+                if (this.config.debug) {
+                    this.logger.debug('Process already terminated', { pid });
+                }
+                return;
+            }
+            throw error;
+        }
+        // Wait for grace period
+        await this.sleep(SIGKILL_GRACE_PERIOD_MS);
+        // Check if still running and send SIGKILL
+        try {
+            // process.kill(pid, 0) checks if process exists
+            process.kill(pid, 0);
+            // Process still running, send SIGKILL
+            if (this.config.debug) {
+                this.logger.debug('Process did not terminate gracefully, sending SIGKILL', { pid });
+            }
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // Process is already dead, which is fine
+        }
+    }
+    /**
+     * Kill a process immediately with SIGKILL
+     */
+    async killProcess(pid) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch (error) {
+            // ESRCH means process doesn't exist, which is fine
+            if (error.code !== 'ESRCH') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Finish a task and clean up timers
+     */
+    finishTask(taskId, status) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            return;
+        }
+        const now = Date.now();
+        task.status = status;
+        task.endedAt = now;
+        task.durationMs = now - task.startedAt;
+        // Clear timers
+        const timer = this.timers.get(taskId);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(taskId);
+        }
+        const warningTimer = this.warningTimers.get(taskId);
+        if (warningTimer) {
+            clearTimeout(warningTimer);
+            this.warningTimers.delete(taskId);
+        }
+        if (this.config.debug) {
+            this.logger.debug('Task finished', {
+                taskId,
+                status,
+                durationMs: task.durationMs,
+                description: task.description,
+            });
+        }
+    }
+    /**
+     * Sleep for a specified duration
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Create a TaskRunner with environment-based configuration
+ *
+ * Environment variables:
+ * - TASK_TIMEOUT_MS: Timeout in milliseconds (default: 600000)
+ * - DEBUG: Enable debug logging (default: false)
+ */
+export function createTaskRunner(config) {
+    return new TaskRunner(config);
+}
+/**
+ * Global TaskRunner instance for singleton usage
+ */
+let globalTaskRunner = null;
+/**
+ * Get or create the global TaskRunner instance
+ */
+export function getGlobalTaskRunner() {
+    if (!globalTaskRunner) {
+        globalTaskRunner = createTaskRunner();
+    }
+    return globalTaskRunner;
+}
+/**
+ * Set a custom global TaskRunner instance
+ */
+export function setGlobalTaskRunner(runner) {
+    globalTaskRunner = runner;
+}
+/**
+ * Dispose of the global TaskRunner instance
+ */
+export function disposeGlobalTaskRunner() {
+    if (globalTaskRunner) {
+        globalTaskRunner.dispose();
+        globalTaskRunner = null;
+    }
+}
+export default TaskRunner;
+//# sourceMappingURL=TaskRunner.js.map

package/dist/src/services/TaskRunner.js.map

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

package/dist/src/services/TransformationService.d.ts

@@ -0,0 +1,167 @@
+/**
+ * SMI-1788: TransformationService - Orchestrate skill optimization pipeline
+ *
+ * The central service for transforming community skills into optimized versions.
+ * Coordinates the full pipeline:
+ * 1. SkillAnalyzer - Analyze skill for optimization patterns
+ * 2. SkillDecomposer - Decompose large skills into sub-skills
+ * 3. SubagentGenerator - Generate companion subagent definitions
+ * 4. Caching - Cache transformed skills for reuse
+ *
+ * Implements the hybrid approach:
+ * - Hot skills (>100 installs): Pre-transformed, cached
+ * - Warm skills (10-100 installs): JIT on first install, cached
+ * - Cold skills (<10 installs): JIT on demand, short TTL
+ *
+ * Part of the Skillsmith Optimization Layer.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+import { type SkillAnalysis } from './SkillAnalyzer.js';
+import { type SubagentDefinition } from './SubagentGenerator.js';
+/**
+ * Full transformation result for a skill
+ */
+export interface TransformationResult {
+    /** Whether transformation was applied */
+    transformed: boolean;
+    /** The optimized main SKILL.md content */
+    mainSkillContent: string;
+    /** Sub-skills (if decomposed) */
+    subSkills: Array<{
+        filename: string;
+        content: string;
+    }>;
+    /** Companion subagent (if generated) */
+    subagent?: SubagentDefinition;
+    /** CLAUDE.md integration snippet */
+    claudeMdSnippet?: string;
+    /** Transformation statistics */
+    stats: TransformationStats;
+    /** Analysis that informed the transformation */
+    analysis: SkillAnalysis;
+    /** Attribution footer added to content */
+    attribution: string;
+}
+/**
+ * Statistics about the transformation
+ */
+export interface TransformationStats {
+    /** Original content line count */
+    originalLines: number;
+    /** Optimized main skill line count */
+    optimizedLines: number;
+    /** Number of sub-skills extracted */
+    subSkillCount: number;
+    /** Whether Task() calls were parallelized */
+    tasksParallelized: boolean;
+    /** Whether subagent was generated */
+    subagentGenerated: boolean;
+    /** Estimated token reduction percentage */
+    tokenReductionPercent: number;
+    /** Transformation duration in ms */
+    transformDurationMs: number;
+}
+/**
+ * Configuration for TransformationService
+ */
+export interface TransformationServiceOptions {
+    /** Cache TTL in seconds (default: 3600 = 1 hour) */
+    cacheTtl?: number;
+    /** Enable caching (default: true) */
+    enableCache?: boolean;
+    /** Force re-transformation even if cached (default: false) */
+    forceTransform?: boolean;
+    /** Transformation version for cache invalidation */
+    version?: string;
+}
+/**
+ * TransformationService orchestrates the skill optimization pipeline
+ */
+export declare class TransformationService {
+    private cache;
+    private options;
+    /**
+     * Create a new TransformationService
+     *
+     * @param db - Database connection (optional, for caching)
+     * @param options - Service configuration
+     */
+    constructor(db?: DatabaseType, options?: TransformationServiceOptions);
+    /**
+     * Transform a skill through the full optimization pipeline
+     *
+     * @param skillId - Unique identifier for the skill (for caching)
+     * @param skillName - Human-readable skill name
+     * @param description - Skill description
+     * @param content - The full SKILL.md content
+     * @returns Transformation result
+     */
+    transform(skillId: string, skillName: string, description: string, content: string): Promise<TransformationResult>;
+    /**
+     * Transform without caching (for testing or one-off transforms)
+     *
+     * SMI-1798: Note that this is NOT a synchronous I/O operation - the name
+     * indicates it runs without async cache operations.
+     *
+     * @param skillName - Human-readable skill name
+     * @param description - Skill description
+     * @param content - The full SKILL.md content
+     * @returns Transformation result
+     */
+    transformWithoutCache(skillName: string, description: string, content: string): TransformationResult;
+    /**
+     * Check if a skill would benefit from transformation without fully transforming
+     *
+     * @param content - The SKILL.md content
+     * @returns Analysis with transformation recommendations
+     */
+    analyze(content: string): SkillAnalysis;
+    /**
+     * Get cached transformation if available and valid
+     */
+    private getCachedTransformation;
+    /**
+     * Cache a transformation result
+     */
+    private cacheTransformation;
+    /**
+     * Build cache key for a skill
+     */
+    private buildCacheKey;
+    /**
+     * SMI-1790: Compute SHA-256 hash for content comparison
+     * Uses cryptographic hash for reliable cache invalidation
+     */
+    private hashContent;
+    /**
+     * Create minimal result for skills that don't need transformation
+     */
+    private createMinimalResult;
+    /**
+     * Build full transformation result
+     */
+    private buildResult;
+    /**
+     * Clear transformation cache
+     */
+    clearCache(): number;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        enabled: boolean;
+        ttl: number;
+        version: string;
+    };
+}
+/**
+ * Create a standalone transformation (no caching)
+ *
+ * @param skillName - Human-readable skill name
+ * @param description - Skill description
+ * @param content - The full SKILL.md content
+ * @returns Transformation result
+ */
+export declare function transformSkill(skillName: string, description: string, content: string): TransformationResult;
+export default TransformationService;
+//# sourceMappingURL=TransformationService.d.ts.map

package/dist/src/services/TransformationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransformationService.d.ts","sourceRoot":"","sources":["../../../src/services/TransformationService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG9D,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAM1F,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,wBAAwB,CAAA;AAE/B;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAA;IAEpB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,CAAA;IAExB,iCAAiC;IACjC,SAAS,EAAE,KAAK,CAAC;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;KAChB,CAAC,CAAA;IAEF,wCAAwC;IACxC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAE7B,oCAAoC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB,gCAAgC;IAChC,KAAK,EAAE,mBAAmB,CAAA;IAE1B,gDAAgD;IAChD,QAAQ,EAAE,aAAa,CAAA;IAEvB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAA;IAErB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAA;IAEtB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAA;IAErB,6CAA6C;IAC7C,iBAAiB,EAAE,OAAO,CAAA;IAE1B,qCAAqC;IACrC,iBAAiB,EAAE,OAAO,CAAA;IAE1B,2CAA2C;IAC3C,qBAAqB,EAAE,MAAM,CAAA;IAE7B,oCAAoC;IACpC,mBAAmB,EAAE,MAAM,CAAA;CAC5B;AAYD;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;IAExB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAsBD;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,OAAO,CAAwC;IAEvD;;;;;OAKG;gBACS,EAAE,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,4BAA4B;IAKrE;;;;;;;;OAQG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,oBAAoB,CAAC;IAmEhC;;;;;;;;;;OAUG;IACH,qBAAqB,CACnB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,oBAAoB;IAqCvB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa;IAIvC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA6B/B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2B3B;;OAEG;IACH,OAAO,CAAC,WAAW;IA8CnB;;OAEG;IACH,UAAU,IAAI,MAAM;IAKpB;;OAEG;IACH,aAAa,IAAI;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAOpE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,oBAAoB,CAGtB;AAED,eAAe,qBAAqB,CAAA"}