@skillsmith/core 0.5.4 → 0.5.6

package/dist/services/TaskRunner.js

@@ -0,0 +1,362 @@
+/**
+ * SMI-1662: TaskRunner - Background Task Timeout Management
+ * @see SMI-2741: Types split to TaskRunner.types.ts, process utils to TaskRunner.process.ts
+ *
+ * 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';
+import { DEFAULT_TASK_TIMEOUT_MS, WARNING_THRESHOLD_RATIO, } from './TaskRunner.types.js';
+import { gracefulShutdown, killProcess } from './TaskRunner.process.js';
+export { DEFAULT_TASK_TIMEOUT_MS, SIGKILL_GRACE_PERIOD_MS, WARNING_THRESHOLD_RATIO, } from './TaskRunner.types.js';
+export { gracefulShutdown, killProcess, sleep } from './TaskRunner.process.js';
+/**
+ * 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 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 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);
+    }
+    /**
+     * 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,
+            });
+        }
+    }
+}
+/**
+ * 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/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/services/TaskRunner.process.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview TaskRunner Process Management Utilities
+ * @module @skillsmith/core/services/TaskRunner.process
+ * @see SMI-1662: TaskRunner - Background Task Timeout Management
+ * @see SMI-2741: Split from TaskRunner.ts to meet 500-line standard
+ *
+ * Low-level process lifecycle management for background task cleanup:
+ * - Graceful shutdown with SIGTERM → SIGKILL escalation
+ * - Immediate kill with SIGKILL
+ * - Sleep utility for grace period waiting
+ */
+/**
+ * Gracefully shutdown a process: SIGTERM -> wait -> SIGKILL
+ *
+ * Sends SIGTERM first to allow graceful shutdown, waits for the
+ * grace period, then escalates to SIGKILL if the process is still running.
+ *
+ * @param pid - Process ID to shutdown
+ */
+export declare function gracefulShutdown(pid: number): Promise<void>;
+/**
+ * Kill a process immediately with SIGKILL
+ *
+ * @param pid - Process ID to kill
+ */
+export declare function killProcess(pid: number): Promise<void>;
+/**
+ * Sleep for a specified duration
+ *
+ * @param ms - Duration in milliseconds
+ */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=TaskRunner.process.d.ts.map

package/dist/services/TaskRunner.process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskRunner.process.d.ts","sourceRoot":"","sources":["../../src/services/TaskRunner.process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBjE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS5D;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/services/TaskRunner.process.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview TaskRunner Process Management Utilities
+ * @module @skillsmith/core/services/TaskRunner.process
+ * @see SMI-1662: TaskRunner - Background Task Timeout Management
+ * @see SMI-2741: Split from TaskRunner.ts to meet 500-line standard
+ *
+ * Low-level process lifecycle management for background task cleanup:
+ * - Graceful shutdown with SIGTERM → SIGKILL escalation
+ * - Immediate kill with SIGKILL
+ * - Sleep utility for grace period waiting
+ */
+import { SIGKILL_GRACE_PERIOD_MS } from './TaskRunner.types.js';
+/**
+ * Gracefully shutdown a process: SIGTERM -> wait -> SIGKILL
+ *
+ * Sends SIGTERM first to allow graceful shutdown, waits for the
+ * grace period, then escalates to SIGKILL if the process is still running.
+ *
+ * @param pid - Process ID to shutdown
+ */
+export async function gracefulShutdown(pid) {
+    // First, send SIGTERM for graceful shutdown
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (error) {
+        // Process might already be dead
+        if (error.code === 'ESRCH') {
+            return;
+        }
+        throw error;
+    }
+    // Wait for grace period
+    await 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
+        process.kill(pid, 'SIGKILL');
+    }
+    catch {
+        // Process is already dead, which is fine
+    }
+}
+/**
+ * Kill a process immediately with SIGKILL
+ *
+ * @param pid - Process ID to kill
+ */
+export async function killProcess(pid) {
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch (error) {
+        // ESRCH means process doesn't exist, which is fine
+        if (error.code !== 'ESRCH') {
+            throw error;
+        }
+    }
+}
+/**
+ * Sleep for a specified duration
+ *
+ * @param ms - Duration in milliseconds
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=TaskRunner.process.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TaskRunner.process.js","sourceRoot":"","sources":["../../src/services/TaskRunner.process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE/D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,4CAA4C;IAC5C,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gCAAgC;QAChC,IAAK,KAA+B,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YACtD,OAAM;QACR,CAAC;QACD,MAAM,KAAK,CAAA;IACb,CAAC;IAED,wBAAwB;IACxB,MAAM,KAAK,CAAC,uBAAuB,CAAC,CAAA;IAEpC,0CAA0C;IAC1C,IAAI,CAAC;QACH,gDAAgD;QAChD,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QACpB,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mDAAmD;QACnD,IAAK,KAA+B,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YACtD,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AAC1D,CAAC"}

package/dist/services/TaskRunner.types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview TaskRunner Type Definitions and Constants
+ * @module @skillsmith/core/services/TaskRunner.types
+ * @see SMI-1662: TaskRunner - Background Task Timeout Management
+ * @see SMI-2741: Split from TaskRunner.ts to meet 500-line standard
+ */
+import type { Logger } from '../utils/logger.js';
+/**
+ * Default timeout: 10 minutes (600000ms)
+ */
+export declare const DEFAULT_TASK_TIMEOUT_MS = 600000;
+/**
+ * Grace period before SIGKILL after SIGTERM: 5 seconds
+ */
+export declare const SIGKILL_GRACE_PERIOD_MS = 5000;
+/**
+ * Warning threshold: 80% of timeout
+ */
+export declare const WARNING_THRESHOLD_RATIO = 0.8;
+/**
+ * Configuration options for TaskRunner
+ */
+export interface TaskRunnerConfig {
+    /** Timeout in milliseconds (default: 600000 = 10 minutes) */
+    timeoutMs?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom logger instance */
+    logger?: Logger;
+    /** Callback when a task times out */
+    onTimeout?: (task: TrackedTask) => void;
+    /** Callback when warning threshold is reached */
+    onWarning?: (task: TrackedTask, remainingMs: number) => void;
+}
+/**
+ * Status of a tracked task
+ */
+export type TaskStatus = 'running' | 'completed' | 'failed' | 'timeout' | 'killed';
+/**
+ * A tracked background task
+ */
+export interface TrackedTask {
+    /** Unique task identifier */
+    id: string;
+    /** Process ID of the background task */
+    pid: number;
+    /** Human-readable description */
+    description: string;
+    /** When the task started */
+    startedAt: number;
+    /** Current status */
+    status: TaskStatus;
+    /** When the task completed/failed/timed out */
+    endedAt?: number;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Whether warning was issued */
+    warningIssued: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Result of a cleanup operation
+ */
+export interface CleanupResult {
+    /** Number of tasks cleaned up */
+    cleaned: number;
+    /** Task IDs that were cleaned */
+    taskIds: string[];
+    /** Any errors encountered */
+    errors: Array<{
+        taskId: string;
+        error: string;
+    }>;
+}
+//# sourceMappingURL=TaskRunner.types.d.ts.map

package/dist/services/TaskRunner.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskRunner.types.d.ts","sourceRoot":"","sources":["../../src/services/TaskRunner.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAMhD;;GAEG;AACH,eAAO,MAAM,uBAAuB,SAAS,CAAA;AAE7C;;GAEG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAA;AAE3C;;GAEG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAM1C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qCAAqC;IACrC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;IACvC,iDAAiD;IACjD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7D;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AAElF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,qBAAqB;IACrB,MAAM,EAAE,UAAU,CAAA;IAClB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,aAAa,EAAE,OAAO,CAAA;IACtB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,iCAAiC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,6BAA6B;IAC7B,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACjD"}

package/dist/services/TaskRunner.types.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview TaskRunner Type Definitions and Constants
+ * @module @skillsmith/core/services/TaskRunner.types
+ * @see SMI-1662: TaskRunner - Background Task Timeout Management
+ * @see SMI-2741: Split from TaskRunner.ts to meet 500-line standard
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * 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;
+//# sourceMappingURL=TaskRunner.types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TaskRunner.types.js","sourceRoot":"","sources":["../../src/services/TaskRunner.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAA;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAA;AAE3C;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA"}