@mxf-dev/core 2.0.5 → 3.1.0

package/src/services/BackgroundTaskManager.ts

@@ -39,7 +39,10 @@ import { AgentId, ChannelId } from '../types/ChannelContext.js';
 import { Logger } from '../utils/Logger.js';
 import { Events } from '../events/EventNames.js';
 import { EventBus } from '../events/EventBus.js';
-import { buildShellChildEnv } from '../protocols/mcp/security/McpToolPolicy.js';
+import {
+    buildShellChildEnv,
+    resolveWorkspacePath
+} from '../protocols/mcp/security/McpToolPolicy.js';
 import {
     createShellExecutionProgressPayload,
     createShellBackgroundStartedPayload,
@@ -106,6 +109,12 @@ export interface BackgroundTaskInfo {
     channelId: ChannelId;
 }
 
+/** Authenticated principal allowed to inspect or mutate a background task. */
+export interface BackgroundTaskPrincipal {
+    agentId: AgentId;
+    channelId: ChannelId;
+}
+
 /** Internal task entry extending BackgroundTask with the child process handle and tracking metadata */
 interface InternalTask extends BackgroundTask {
     /** The spawned child process (cleared after exit) */
@@ -116,12 +125,19 @@ interface InternalTask extends BackgroundTask {
     lastProgressEmit: number;
     /** Timeout timer handle (if a timeout was specified) */
     timeoutTimer?: ReturnType<typeof setTimeout>;
+    /** SIGTERM-to-SIGKILL escalation timer. */
+    forceKillTimer?: ReturnType<typeof setTimeout>;
+    /** Settles after terminal process callbacks and their final event emission complete. */
+    completion: Promise<void>;
+    resolveCompletion: () => void;
+    /** Guards Node's error-then-close sequence from reporting completion twice. */
+    terminalFinalized: boolean;
 }
 
 // ---- BackgroundTaskManager ----
 
 export class BackgroundTaskManager {
-    private static instance: BackgroundTaskManager;
+    private static instance: BackgroundTaskManager | undefined;
 
     /** Map of taskId -> internal task state */
     private tasks: Map<string, InternalTask> = new Map();
@@ -139,6 +155,8 @@ export class BackgroundTaskManager {
 
     /** Handle for the periodic cleanup timer */
     private cleanupTimer?: ReturnType<typeof setInterval>;
+    private shutdownPromise: Promise<void> | undefined;
+    private isShuttingDown = false;
 
     private constructor() {
         // Start periodic cleanup of completed tasks older than cleanupIntervalMs
@@ -157,6 +175,16 @@ export class BackgroundTaskManager {
         return BackgroundTaskManager.instance;
     }
 
+    /** Stop the live singleton without constructing one solely for teardown. */
+    static async shutdownExisting(): Promise<boolean> {
+        const instance = BackgroundTaskManager.instance;
+        if (!instance) {
+            return false;
+        }
+        await instance.shutdown();
+        return true;
+    }
+
     /**
      * Start a command in the background. Returns immediately with a taskId that
      * can be used to query status, retrieve output, or cancel the task.
@@ -177,6 +205,10 @@ export class BackgroundTaskManager {
         },
         context: { agentId: AgentId; channelId: ChannelId; requestId: string }
     ): Promise<{ taskId: string }> {
+        if (this.isShuttingDown) {
+            throw new Error('BackgroundTaskManager is shutting down');
+        }
+
         // Validate concurrent task limit
         const runningCount = this.getRunningTaskCount();
         if (runningCount >= this.maxConcurrentTasks) {
@@ -196,13 +228,26 @@ export class BackgroundTaskManager {
         // get the same stripped environment the guarded shell path builds.
         const spawnOptions: SpawnOptions = {
             shell: true,
-            cwd: options.workingDirectory || process.cwd(),
+            // The command runs under `sh -c`. On Linux, dash forks the command
+            // rather than exec'ing it, so a signal to the shell's pid left the
+            // real work running and holding the stdio pipes — `close` never
+            // fired and shutdown() waited on it. Each task gets its own process
+            // group and is signalled as a group (see signalTask).
+            detached: process.platform !== 'win32',
+            cwd: resolveWorkspacePath(
+                options.workingDirectory,
+                'BackgroundTaskManager.startBackground'
+            ),
             env: buildShellChildEnv(options.environment),
         };
 
         const childProcess = spawn(command, [], spawnOptions);
 
         // Create the internal task entry
+        let resolveCompletion!: () => void;
+        const completion = new Promise<void>(resolve => {
+            resolveCompletion = resolve;
+        });
         const task: InternalTask = {
             taskId,
             command,
@@ -217,6 +262,9 @@ export class BackgroundTaskManager {
             process: childProcess,
             totalOutputBytes: 0,
             lastProgressEmit: 0,
+            completion,
+            resolveCompletion,
+            terminalFinalized: false,
         };
 
         this.tasks.set(taskId, task);
@@ -257,6 +305,10 @@ export class BackgroundTaskManager {
 
         // Handle process exit
         childProcess.on('close', (code: number | null) => {
+            if (task.terminalFinalized) {
+                return;
+            }
+            task.terminalFinalized = true;
             const exitCode = code ?? 1;
             task.exitCode = exitCode;
             task.endTime = Date.now();
@@ -271,6 +323,10 @@ export class BackgroundTaskManager {
                 clearTimeout(task.timeoutTimer);
                 task.timeoutTimer = undefined;
             }
+            if (task.forceKillTimer) {
+                clearTimeout(task.forceKillTimer);
+                task.forceKillTimer = undefined;
+            }
 
             const elapsedSeconds = (task.endTime - task.startTime) / 1000;
 
@@ -280,27 +336,36 @@ export class BackgroundTaskManager {
             );
 
             // Emit SHELL_BACKGROUND_COMPLETED event
-            EventBus.server.emit(
-                Events.Shell.SHELL_BACKGROUND_COMPLETED,
-                createShellBackgroundCompletedPayload(
-                    task.agentId,
-                    task.channelId,
-                    {
-                        requestId: task.requestId,
-                        taskId,
-                        command: task.command,
-                        exitCode,
-                        isError: exitCode !== 0,
-                        executionTime: (task.endTime! - task.startTime),
-                        outputSize: task.totalOutputBytes
-                    }
-                )
-            );
+            try {
+                EventBus.server.emit(
+                    Events.Shell.SHELL_BACKGROUND_COMPLETED,
+                    createShellBackgroundCompletedPayload(
+                        task.agentId,
+                        task.channelId,
+                        {
+                            requestId: task.requestId,
+                            taskId,
+                            command: task.command,
+                            exitCode,
+                            isError: exitCode !== 0,
+                            executionTime: (task.endTime! - task.startTime),
+                            outputSize: task.totalOutputBytes
+                        }
+                    )
+                );
+            } finally {
+                task.resolveCompletion();
+            }
         });
 
         // Handle spawn errors (e.g., command not found)
         childProcess.on('error', (error: Error) => {
+            if (task.terminalFinalized) {
+                return;
+            }
+            task.terminalFinalized = true;
             task.status = 'failed';
+            task.exitCode = 1;
             task.endTime = Date.now();
             task.process = undefined;
 
@@ -309,28 +374,34 @@ export class BackgroundTaskManager {
                 clearTimeout(task.timeoutTimer);
                 task.timeoutTimer = undefined;
             }
+            if (task.forceKillTimer) {
+                clearTimeout(task.forceKillTimer);
+                task.forceKillTimer = undefined;
+            }
 
             this.logger.error(`Background task error: ${taskId} — ${error.message}`);
 
-            const elapsedSeconds = (task.endTime - task.startTime) / 1000;
-
             // Emit SHELL_BACKGROUND_COMPLETED with failed status
-            EventBus.server.emit(
-                Events.Shell.SHELL_BACKGROUND_COMPLETED,
-                createShellBackgroundCompletedPayload(
-                    task.agentId,
-                    task.channelId,
-                    {
-                        requestId: task.requestId,
-                        taskId,
-                        command: task.command,
-                        exitCode: 1,
-                        isError: true,
-                        executionTime: (task.endTime! - task.startTime),
-                        outputSize: task.totalOutputBytes
-                    }
-                )
-            );
+            try {
+                EventBus.server.emit(
+                    Events.Shell.SHELL_BACKGROUND_COMPLETED,
+                    createShellBackgroundCompletedPayload(
+                        task.agentId,
+                        task.channelId,
+                        {
+                            requestId: task.requestId,
+                            taskId,
+                            command: task.command,
+                            exitCode: 1,
+                            isError: true,
+                            executionTime: (task.endTime! - task.startTime),
+                            outputSize: task.totalOutputBytes
+                        }
+                    )
+                );
+            } finally {
+                task.resolveCompletion();
+            }
         });
 
         // Set up timeout if specified
@@ -340,15 +411,11 @@ export class BackgroundTaskManager {
                     this.logger.warn(
                         `Background task timed out after ${options.timeout}s: ${taskId}`
                     );
-                    task.process.kill('SIGTERM');
-                    // Force kill after 5 seconds if SIGTERM didn't work
-                    setTimeout(() => {
-                        if (task.status === 'running' && task.process) {
-                            task.process.kill('SIGKILL');
-                        }
-                    }, 5000);
+                    this.signalTask(task, 'SIGTERM');
+                    this.scheduleForceKill(task, taskId);
                 }
             }, options.timeout * 1000);
+            task.timeoutTimer.unref?.();
         }
 
         return { taskId };
@@ -360,8 +427,8 @@ export class BackgroundTaskManager {
      * @param taskId - The task identifier returned by startBackground()
      * @returns BackgroundTaskInfo with current status and output preview, or null if not found
      */
-    getTaskStatus(taskId: string): BackgroundTaskInfo | null {
-        const task = this.tasks.get(taskId);
+    getTaskStatus(taskId: string, principal: BackgroundTaskPrincipal): BackgroundTaskInfo | null {
+        const task = this.getOwnedTask(taskId, principal);
         if (!task) {
             return null;
         }
@@ -375,8 +442,8 @@ export class BackgroundTaskManager {
      * @param taskId - The task identifier returned by startBackground()
      * @returns The accumulated stdout output, or null if the task is not found
      */
-    getTaskOutput(taskId: string): string | null {
-        const task = this.tasks.get(taskId);
+    getTaskOutput(taskId: string, principal: BackgroundTaskPrincipal): string | null {
+        const task = this.getOwnedTask(taskId, principal);
         if (!task) {
             return null;
         }
@@ -390,8 +457,8 @@ export class BackgroundTaskManager {
      * @param taskId - The task identifier returned by startBackground()
      * @returns true if the task was found and cancellation was initiated, false otherwise
      */
-    cancelTask(taskId: string): boolean {
-        const task = this.tasks.get(taskId);
+    cancelTask(taskId: string, principal: BackgroundTaskPrincipal): boolean {
+        const task = this.getOwnedTask(taskId, principal);
         if (!task) {
             this.logger.warn(`Cannot cancel task: ${taskId} — task not found`);
             return false;
@@ -419,35 +486,24 @@ export class BackgroundTaskManager {
         }
 
         // Send SIGTERM for graceful shutdown
-        task.process.kill('SIGTERM');
+        this.signalTask(task, 'SIGTERM');
 
         // Escalate to SIGKILL after 5 seconds if still alive
-        const killTimer = setTimeout(() => {
-            if (task.process) {
-                this.logger.warn(`Force-killing background task: ${taskId} (SIGKILL)`);
-                task.process.kill('SIGKILL');
-            }
-        }, 5000);
-
-        // Clean up the kill timer when the process actually exits
-        const originalClose = task.process;
-        originalClose.on('close', () => {
-            clearTimeout(killTimer);
-        });
+        this.scheduleForceKill(task, taskId);
 
         return true;
     }
 
     /**
-     * List all background tasks, optionally filtered by agent.
+     * List background tasks owned by the exact authenticated agent/channel pair.
      *
-     * @param agentId - If provided, only tasks belonging to this agent are returned
+     * @param principal - Authenticated agent and channel identity
      * @returns Array of BackgroundTaskInfo for matching tasks
      */
-    listTasks(agentId?: AgentId): BackgroundTaskInfo[] {
+    listTasks(principal: BackgroundTaskPrincipal): BackgroundTaskInfo[] {
         const results: BackgroundTaskInfo[] = [];
         for (const task of this.tasks.values()) {
-            if (agentId && task.agentId !== agentId) {
+            if (task.agentId !== principal.agentId || task.channelId !== principal.channelId) {
                 continue;
             }
             results.push(this.toTaskInfo(task));
@@ -459,7 +515,19 @@ export class BackgroundTaskManager {
      * Shutdown the manager: cancel all running tasks, clear timers, and release resources.
      * Called during server shutdown to ensure clean process cleanup.
      */
-    shutdown(): void {
+    shutdown(): Promise<void> {
+        if (!this.shutdownPromise) {
+            this.isShuttingDown = true;
+            this.shutdownPromise = this.performShutdown().finally((): void => {
+                if (BackgroundTaskManager.instance === this) {
+                    BackgroundTaskManager.instance = undefined;
+                }
+            });
+        }
+        return this.shutdownPromise;
+    }
+
+    private async performShutdown(): Promise<void> {
         this.logger.info('Shutting down BackgroundTaskManager...');
 
         // Clear the periodic cleanup timer
@@ -468,27 +536,97 @@ export class BackgroundTaskManager {
             this.cleanupTimer = undefined;
         }
 
-        // Cancel all running tasks
+        const completions: Promise<void>[] = [];
+
+        // Terminate every live child and retain ownership until its terminal
+        // callback has emitted the final lifecycle event. A task can already be
+        // marked cancelled while its process is still exiting, so process
+        // ownership — not status — defines what shutdown must drain.
         for (const task of this.tasks.values()) {
-            if (task.status === 'running' && task.process) {
-                // Clear any timeout timers
-                if (task.timeoutTimer) {
-                    clearTimeout(task.timeoutTimer);
-                    task.timeoutTimer = undefined;
-                }
+            if (task.timeoutTimer) {
+                clearTimeout(task.timeoutTimer);
+                task.timeoutTimer = undefined;
+            }
+            if (task.forceKillTimer) {
+                clearTimeout(task.forceKillTimer);
+                task.forceKillTimer = undefined;
+            }
 
-                task.status = 'cancelled';
-                task.endTime = Date.now();
-                task.process.kill('SIGKILL');
-                task.process = undefined;
+            if (!task.terminalFinalized && task.process) {
+                if (task.status === 'running') {
+                    task.status = 'cancelled';
+                }
+                task.endTime ??= Date.now();
+                completions.push(task.completion);
+                this.signalTask(task, 'SIGKILL');
             }
         }
 
+        await Promise.all(completions);
+
         this.logger.info('BackgroundTaskManager shut down successfully');
     }
 
+    private scheduleForceKill(task: InternalTask, taskId: string): void {
+        if (task.forceKillTimer) {
+            clearTimeout(task.forceKillTimer);
+        }
+        task.forceKillTimer = setTimeout(() => {
+            task.forceKillTimer = undefined;
+            if (task.process) {
+                this.logger.warn(`Force-killing background task: ${taskId} (SIGKILL)`);
+                this.signalTask(task, 'SIGKILL');
+            }
+        }, 5000);
+        task.forceKillTimer.unref?.();
+    }
+
+    /**
+     * Deliver a signal to a task's whole process group — the shell and every
+     * process it started — so the work actually stops and its stdio pipes
+     * close. A group that has already exited (ESRCH) is not an error.
+     */
+    private signalTask(task: InternalTask, signal: NodeJS.Signals): void {
+        const child = task.process;
+        if (!child) {
+            return;
+        }
+        // No pid means the process never started, so there is no group to
+        // signal; Windows has no process groups to signal either.
+        if (child.pid === undefined || process.platform === 'win32') {
+            child.kill(signal);
+            return;
+        }
+        try {
+            process.kill(-child.pid, signal);
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'ESRCH') {
+                throw error;
+            }
+        }
+    }
+
     // ---- Private helpers ----
 
+    /**
+     * Resolve a task only when it belongs to the authenticated principal. Returning
+     * null for both missing and foreign task IDs avoids leaking task existence.
+     */
+    private getOwnedTask(
+        taskId: string,
+        principal: BackgroundTaskPrincipal
+    ): InternalTask | null {
+        const task = this.tasks.get(taskId);
+        if (
+            !task ||
+            task.agentId !== principal.agentId ||
+            task.channelId !== principal.channelId
+        ) {
+            return null;
+        }
+        return task;
+    }
+
     /**
      * Append output to a task's buffer with ring-buffer semantics.
      * When the buffer exceeds maxOutputBufferSize, the front is trimmed.

package/src/services/BrowserManager.ts

@@ -74,6 +74,21 @@ export interface BrowserConfig {
     userAgent?: string;
 }
 
+/** Chromium launch flags that preserve its OS sandbox boundary. */
+export const getSecureBrowserLaunchArgs = (): string[] => [
+    '--disable-dev-shm-usage',
+    '--disable-gpu',
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+    '--disable-features=TranslateUI',
+    '--disable-ipc-flooding-protection',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-default-apps',
+    '--disable-extensions'
+];
+
 export class BrowserManager {
     private pools: Map<string, BrowserInstance[]> = new Map();
     private maxPoolSize: number;
@@ -176,21 +191,10 @@ export class BrowserManager {
         const puppeteer = await loadPuppeteer();
         const browser = await puppeteer.launch({
             headless: this.config.headless ?? true,
-            args: [
-                '--no-sandbox',
-                '--disable-setuid-sandbox',
-                '--disable-dev-shm-usage',
-                '--disable-gpu',
-                '--disable-background-timer-throttling',
-                '--disable-backgrounding-occluded-windows',
-                '--disable-renderer-backgrounding',
-                '--disable-features=TranslateUI',
-                '--disable-ipc-flooding-protection',
-                '--no-first-run',
-                '--no-default-browser-check',
-                '--disable-default-apps',
-                '--disable-extensions'
-            ]
+            // Never pass --no-sandbox or --disable-setuid-sandbox. A deployment
+            // that cannot start Chromium with its OS sandbox intact must fail
+            // instead of silently executing hostile pages without isolation.
+            args: getSecureBrowserLaunchArgs()
         });
 
         const instance: BrowserInstance = {
@@ -287,4 +291,4 @@ export class BrowserManager {
         await Promise.all(closePromises);
         this.logger?.info('Browser cleanup completed');
     }
-}
+}