Execution Engine & Concurrency

Relevant source files

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

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

The Execution Engine of SuperAgent-MCP serves as the core orchestration layer for interfacing with external CLI-based agents. It is designed to bridge Model Context Protocol (MCP) clients with specialized agents like Codex, Gemini, and Continue. The engine's primary purpose is to manage the lifecycle of these agent processes, handling everything from input preparation and parallel execution to result parsing and resource cleanup.

Concurrency is a first-class citizen in this architecture, allowing users to "fan out" multiple tasks across different working directories or agents simultaneously. This is achieved through a batch execution model that respects user-defined concurrency limits and per-task timeouts, ensuring efficient use of system resources while preventing runaway processes.

Sources: README.md:1-10, src/server.ts:70-80

Multi-Agent Tool Architecture

The system exposes agents as MCP tools. The primary tools—codex, gemini, and continue—share a common execution pattern but differ in their underlying CLI invocation and configuration requirements.

Core Tools and Purpose

Tool	Engine Backend	Key Characteristics
codex	Codex CLI	Supports full system access, parallel tasks, and specialized system prompts.
gemini	Gemini CLI	Runs in "YOLO mode" with auto-approval enabled for all actions.
continue	Continue CLI	Operates in headless mode; requires CONTINUE_CONFIG_PATH.

Sources: src/server.ts:44-67, README.md:20-30

Execution Flow

When a tool is called, the server parses the request using Zod schemas and hands the workload to a specific batch runner (e.g., runCodexBatch). The batch runner manages the parallelization of individual tasks.

This diagram illustrates the high-level flow from a client request through the server's routing logic to the concurrent task execution.
Sources: src/server.ts:98-150, src/codexAgent.ts:160-170

Concurrency and Task Management

The engine implements a parallel execution model where multiple prompts can be processed at once. The concurrency parameter in tool arguments controls how many tasks are active simultaneously.

Process Spawning and Lifecycle

The engine uses node:child_process to spawn agent CLIs. For Codex, it invokes the exec command with flags like --json for structured output and --dangerously-bypass-approvals-and-sandbox to allow the agent full permissions.

Key lifecycle steps include:

1. Registration: Every spawned process is registered with a processManager to ensure they are tracked for cleanup.
2. Standard I/O Management: Prompts are piped into stdin, while stdout and stderr are collected as chunks.
3. Timeouts: A DEFAULT_TIMEOUT_MS (set to 30 minutes) or a user-provided timeoutMs is enforced via a Promise race. If the timeout is reached, the process is killed using SIGKILL.

Sources: src/codexAgent.ts:48-60, src/codexAgent.ts:175-205, src/processManager.ts

Sequential Thinking and Safety

While tasks run in parallel, the processManager handles signal handlers (like SIGINT or SIGTERM) to perform a graceful shutdown of all active subprocesses, preventing zombie processes from lingering after the MCP server exits.

Sources: src/server.ts:246-250, src/processManager.ts

Data Extraction and Result Formatting

The engine transforms raw CLI output into structured data for the MCP client.

Event Parsing

Agents often output results as multiple JSON lines. The engine implements a parseJsonLines function to iterate through stdout, attempting to parse each line. If parsing fails, the line is treated as a standard log entry.

This sequence shows the interaction between the engine and the underlying CLI during a single task execution.
Sources: src/codexAgent.ts:133-150, src/codexAgent.ts:170-185

Assistant Reply Extraction

The engine identifies the actual response text by looking for specific message types within the parsed JSON events. It specifically scans for agent_message or assistant_message types and extracts the text field from the message content.

Sources: src/codexAgent.ts:71-100

Configuration and Agent Injection

The engine supports dynamic system prompt injection through the "Agent Library."

System Prompt Hierarchy

When invoking an agent, the engine builds a hierarchical prompt:

1. META_INSTRUCTION: A base instruction informing the agent it is being invoked via MCP.
2. Agent System Prompt: The content of a specific markdown file loaded from ~/.superagent/agents.
3. User Request: The actual task provided in the MCP tool call.

const fullPrompt = META_INSTRUCTION +
  (options.agentSystemPrompt ? options.agentSystemPrompt + "\n\nUser request:\n" : "") +
  options.prompt;

Sources: src/codexAgent.ts:152-159, src/codexAgent.ts:193-197

Agent Loading

The agentLoader module manages the synchronization of these prompts. On post-installation or startup, it ensures the ~/.superagent/agents directory exists and copies bundled agents (like technical-writer or deep-research-agent) if they aren't already present locally.

Sources: src/agentLoader.ts:40-65, src/agentLoader.ts:79-110

Technical Summary of Components

Component	File Path	Responsibility
invokeCodex	src/codexAgent.ts	Spawns processes, manages stdin/stdout, and handles per-task timeouts.
runCodexBatch	src/runner.ts	Orchestrates the parallel execution of multiple invokeCodex calls.
setupSignalHandlers	src/processManager.ts	Ensures all concurrent subprocesses are terminated on server exit.
loadAgents	src/agentLoader.ts	Dynamically loads specialized system prompts from the local filesystem.
CallToolRequestSchema	src/server.ts	Validates incoming MCP requests and routes them to the correct execution path.

Sources: src/server.ts:12-25, src/codexAgent.ts:168, src/agentLoader.ts:85