Process Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/processManager.ts
• src/server.ts
• src/codexAgent.ts
• src/geminiAgent.ts
• README.md

The Process Management system in SuperAgent MCP is responsible for the lifecycle, parallel execution, and graceful termination of external CLI agent processes. It acts as a bridge between the Model Context Protocol (MCP) server and various command-line tools like Codex, Gemini, and Continue. The system ensures that background tasks are tracked, timed out appropriately, and cleaned up during server shutdown to prevent orphaned processes.

The primary scope includes spawning child processes with specific environment configurations, managing concurrent execution through batch runners, and implementing signal handlers for system-level interrupts. This robust management allows the server to handle high-concurrency requests while maintaining system stability.

Sources: README.md:1-12, src/server.ts:258-265, src/processManager.ts

Architecture and Lifecycle

Process management is centralized around a registry that tracks active child processes. When a tool is invoked via the MCP server, it triggers an agent-specific invocation function that spawns a new process.

Process Registry and Cleanup

The processManager.ts module maintains a collection of active ChildProcess instances. It provides a registration mechanism so that any spawned agent (Codex, Gemini, etc.) can be tracked globally by the server.

Signal Handling

To ensure reliability, the system traps standard termination signals. Upon receiving a SIGINT or SIGTERM, the setupSignalHandlers function iterates through the registry and kills all active processes before exiting the main thread.

Sources: src/processManager.ts:17-35, src/server.ts:259

Agent Invocation Logic

Processes are spawned using Node.js child_process.spawn. Each agent has a specialized invoker that manages its specific command-line arguments and communication pipes.

Execution Components

Component	Functionality	Source File
invokeCodex	Spawns codex CLI with JSON events and meta-instructions.	src/codexAgent.ts:114
invokeGemini	Spawns gemini CLI with YOLO mode and JSON output.	src/geminiAgent.ts:88
registerProcess	Adds a child process to the global cleanup tracking list.	src/processManager.ts:12
setupSignalHandlers	Attaches listeners for SIGINT and SIGTERM.	src/processManager.ts:17

Timeout Management

Every process is wrapped in a timeout promise to prevent infinite execution. If an agent process exceeds the timeoutMs (defaulting to 30 minutes), the system sends a SIGKILL to the child process and rejects the invocation.

Parallel Execution and Concurrency

The system supports running multiple tasks in parallel by "fanning out" CLI tasks. The server.ts module coordinates these batches using schemas that define concurrency limits.

Configuration Parameters

The process management behavior is controlled via arguments passed to the tools:

• Concurrency: Determines how many agent processes run simultaneously.
• TimeoutMs: Individual task duration limit.
• WorkingDirectory: The cwd for the spawned process, allowing access to different project folders.

Sources: src/server.ts:46-64, README.md:25-30

Communication Flow

Agents communicate primarily through standard I/O pipes:

1. stdin: Used by the server to send the META_INSTRUCTION and user prompts to agents like Codex.
2. stdout: Captured by the server to parse JSON event lines or raw responses.
3. stderr: Monitored for error reporting and debugging.

Sources: src/codexAgent.ts:132-135, src/geminiAgent.ts:104-108

Summary

Process management in SuperAgent MCP provides the critical infrastructure for executing CLI-based AI agents reliably. By implementing a global process registry and strict signal handling, it prevents resource leaks. The combination of per-task timeouts and configurable concurrency ensures that parallel agent executions remain bounded and manageable within the MCP server environment.