This is page 12 of 12. Use http://codebase.md/minipuft/claude-prompts-mcp?lines=false&page={x} to view the full context.
# Directory Structure
```
├── .actrc
├── .gitattributes
├── .github
│ └── workflows
│ ├── ci.yml
│ ├── mcp-compliance.yml
│ └── pr-validation.yml
├── .gitignore
├── agent.md
├── assets
│ └── logo.png
├── CLAUDE.md
├── config
│ └── framework-state.json
├── docs
│ ├── architecture.md
│ ├── chain-modification-examples.md
│ ├── contributing.md
│ ├── enhanced-gate-system.md
│ ├── execution-architecture-guide.md
│ ├── installation-guide.md
│ ├── mcp-tool-usage-guide.md
│ ├── mcp-tools-reference.md
│ ├── prompt-format-guide.md
│ ├── prompt-management.md
│ ├── prompt-vs-template-guide.md
│ ├── README.md
│ ├── template-development-guide.md
│ ├── TODO.md
│ ├── troubleshooting.md
│ └── version-history.md
├── LICENSE
├── local-test.sh
├── plans
│ ├── nunjucks-dynamic-chain-orchestration.md
│ ├── outputschema-realtime-progress-and-validation.md
│ ├── parallel-conditional-execution-analysis.md
│ ├── sqlite-storage-migration.md
│ └── symbolic-command-language-implementation.md
├── README.md
├── scripts
│ ├── setup-windows-testing.sh
│ ├── test_server.js
│ ├── test-all-platforms.sh
│ └── windows-tests
│ ├── test-windows-paths.js
│ ├── test-windows-startup.sh
│ └── windows-env.sh
└── server
├── config
│ ├── framework-state.json
│ └── tool-descriptions.json
├── config.json
├── jest.config.cjs
├── LICENSE
├── package-lock.json
├── package.json
├── prompts
│ ├── analysis
│ │ ├── advanced_analysis_engine.md
│ │ ├── content_analysis.md
│ │ ├── deep_analysis.md
│ │ ├── deep_research.md
│ │ ├── markdown_notebook.md
│ │ ├── note_integration.md
│ │ ├── note_refinement.md
│ │ ├── notes.md
│ │ ├── progressive_research.md
│ │ ├── prompts.json
│ │ ├── query_refinement.md
│ │ └── review.md
│ ├── architecture
│ │ ├── prompts.json
│ │ └── strategic-system-alignment.md
│ ├── content_processing
│ │ ├── format_enhancement.md
│ │ ├── noteIntegration.md
│ │ ├── obsidian_metadata_optimizer.md
│ │ ├── prompts.json
│ │ ├── vault_related_notes_finder.md
│ │ └── video_notes_enhanced.md
│ ├── debugging
│ │ ├── analyze_logs.md
│ │ └── prompts.json
│ ├── development
│ │ ├── analyze_code_structure.md
│ │ ├── analyze_file_structure.md
│ │ ├── code_review_optimization_chain.md
│ │ ├── component_flow_analysis.md
│ │ ├── create_modularization_plan.md
│ │ ├── detect_code_issues.md
│ │ ├── detect_project_commands.md
│ │ ├── expert_code_implementation.md
│ │ ├── generate_comprehensive_claude_md.md
│ │ ├── prompts.json
│ │ ├── strategicImplement.md
│ │ ├── suggest_code_improvements.md
│ │ └── transform_code_to_modules.md
│ ├── documentation
│ │ ├── create_docs_chain.md
│ │ ├── docs-content-creation.md
│ │ ├── docs-content-planning.md
│ │ ├── docs-final-assembly.md
│ │ ├── docs-project-analysis.md
│ │ ├── docs-review-refinement.md
│ │ └── prompts.json
│ ├── education
│ │ ├── prompts.json
│ │ └── vault_integrated_notes.md
│ ├── general
│ │ ├── diagnose.md
│ │ └── prompts.json
│ ├── promptsConfig.json
│ └── testing
│ ├── final_verification_test.md
│ └── prompts.json
├── README.md
├── scripts
│ └── validate-dependencies.js
├── src
│ ├── api
│ │ └── index.ts
│ ├── chain-session
│ │ └── manager.ts
│ ├── config
│ │ └── index.ts
│ ├── Dockerfile
│ ├── execution
│ │ ├── context
│ │ │ ├── context-resolver.ts
│ │ │ ├── framework-injector.ts
│ │ │ └── index.ts
│ │ ├── index.ts
│ │ ├── parsers
│ │ │ ├── argument-parser.ts
│ │ │ ├── index.ts
│ │ │ └── unified-command-parser.ts
│ │ └── types.ts
│ ├── frameworks
│ │ ├── framework-manager.ts
│ │ ├── framework-state-manager.ts
│ │ ├── index.ts
│ │ ├── integration
│ │ │ ├── framework-semantic-integration.ts
│ │ │ └── index.ts
│ │ ├── methodology
│ │ │ ├── guides
│ │ │ │ ├── 5w1h-guide.ts
│ │ │ │ ├── cageerf-guide.ts
│ │ │ │ ├── react-guide.ts
│ │ │ │ └── scamper-guide.ts
│ │ │ ├── index.ts
│ │ │ ├── interfaces.ts
│ │ │ └── registry.ts
│ │ ├── prompt-guidance
│ │ │ ├── index.ts
│ │ │ ├── methodology-tracker.ts
│ │ │ ├── service.ts
│ │ │ ├── system-prompt-injector.ts
│ │ │ └── template-enhancer.ts
│ │ └── types
│ │ ├── index.ts
│ │ ├── integration-types.ts
│ │ ├── methodology-types.ts
│ │ └── prompt-guidance-types.ts
│ ├── gates
│ │ ├── constants.ts
│ │ ├── core
│ │ │ ├── gate-definitions.ts
│ │ │ ├── gate-loader.ts
│ │ │ ├── gate-validator.ts
│ │ │ ├── index.ts
│ │ │ └── temporary-gate-registry.ts
│ │ ├── definitions
│ │ │ ├── code-quality.json
│ │ │ ├── content-structure.json
│ │ │ ├── educational-clarity.json
│ │ │ ├── framework-compliance.json
│ │ │ ├── research-quality.json
│ │ │ ├── security-awareness.json
│ │ │ └── technical-accuracy.json
│ │ ├── gate-state-manager.ts
│ │ ├── guidance
│ │ │ ├── FrameworkGuidanceFilter.ts
│ │ │ └── GateGuidanceRenderer.ts
│ │ ├── index.ts
│ │ ├── intelligence
│ │ │ ├── GatePerformanceAnalyzer.ts
│ │ │ └── GateSelectionEngine.ts
│ │ ├── templates
│ │ │ ├── code_quality_validation.md
│ │ │ ├── educational_clarity_validation.md
│ │ │ ├── framework_compliance_validation.md
│ │ │ ├── research_self_validation.md
│ │ │ ├── security_validation.md
│ │ │ ├── structure_validation.md
│ │ │ └── technical_accuracy_validation.md
│ │ └── types.ts
│ ├── index.ts
│ ├── logging
│ │ └── index.ts
│ ├── mcp-tools
│ │ ├── config-utils.ts
│ │ ├── constants.ts
│ │ ├── index.ts
│ │ ├── prompt-engine
│ │ │ ├── core
│ │ │ │ ├── engine.ts
│ │ │ │ ├── executor.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── processors
│ │ │ │ ├── response-formatter.ts
│ │ │ │ └── template-processor.ts
│ │ │ └── utils
│ │ │ ├── category-extractor.ts
│ │ │ ├── classification.ts
│ │ │ ├── context-builder.ts
│ │ │ └── validation.ts
│ │ ├── prompt-manager
│ │ │ ├── analysis
│ │ │ │ ├── comparison-engine.ts
│ │ │ │ ├── gate-analyzer.ts
│ │ │ │ └── prompt-analyzer.ts
│ │ │ ├── core
│ │ │ │ ├── index.ts
│ │ │ │ ├── manager.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── operations
│ │ │ │ └── file-operations.ts
│ │ │ ├── search
│ │ │ │ ├── filter-parser.ts
│ │ │ │ └── prompt-matcher.ts
│ │ │ └── utils
│ │ │ ├── category-manager.ts
│ │ │ └── validation.ts
│ │ ├── shared
│ │ │ └── structured-response-builder.ts
│ │ ├── system-control.ts
│ │ ├── tool-description-manager.ts
│ │ └── types
│ │ └── shared-types.ts
│ ├── metrics
│ │ ├── analytics-service.ts
│ │ ├── index.ts
│ │ └── types.ts
│ ├── performance
│ │ ├── index.ts
│ │ └── monitor.ts
│ ├── prompts
│ │ ├── category-manager.ts
│ │ ├── converter.ts
│ │ ├── file-observer.ts
│ │ ├── hot-reload-manager.ts
│ │ ├── index.ts
│ │ ├── loader.ts
│ │ ├── promptUtils.ts
│ │ ├── registry.ts
│ │ └── types.ts
│ ├── runtime
│ │ ├── application.ts
│ │ └── startup.ts
│ ├── semantic
│ │ ├── configurable-semantic-analyzer.ts
│ │ └── integrations
│ │ ├── index.ts
│ │ └── llm-clients.ts
│ ├── server
│ │ ├── index.ts
│ │ └── transport
│ │ └── index.ts
│ ├── smithery.yaml
│ ├── text-references
│ │ ├── conversation.ts
│ │ └── index.ts
│ ├── types
│ │ └── index.ts
│ ├── types.ts
│ └── utils
│ ├── chainUtils.ts
│ ├── errorHandling.ts
│ ├── global-resource-tracker.ts
│ ├── index.ts
│ └── jsonUtils.ts
├── tests
│ ├── ci-startup-validation.js
│ ├── enhanced-validation
│ │ ├── contract-validation
│ │ │ ├── contract-test-suite.js
│ │ │ ├── interface-contracts.js
│ │ │ └── interface-contracts.ts
│ │ ├── environment-validation
│ │ │ ├── environment-parity-checker.js
│ │ │ └── environment-test-suite.js
│ │ ├── lifecycle-validation
│ │ │ ├── lifecycle-test-suite.js
│ │ │ └── process-lifecycle-validator.js
│ │ └── validation-orchestrator.js
│ ├── helpers
│ │ └── test-helpers.js
│ ├── integration
│ │ ├── mcp-tools.test.ts
│ │ ├── server-startup.test.ts
│ │ └── unified-parsing-integration.test.ts
│ ├── performance
│ │ ├── parsing-system-benchmark.test.ts
│ │ └── server-performance.test.ts
│ ├── scripts
│ │ ├── consolidated-tools.js
│ │ ├── establish-performance-baselines.js
│ │ ├── functional-mcp-validation.js
│ │ ├── integration-mcp-tools.js
│ │ ├── integration-routing-system.js
│ │ ├── integration-server-startup.js
│ │ ├── integration-unified-parsing.js
│ │ ├── methodology-guides.js
│ │ ├── performance-memory.js
│ │ ├── runtime-integration.js
│ │ ├── unit-conversation-manager.js
│ │ ├── unit-semantic-analyzer.js
│ │ └── unit-unified-parsing.js
│ ├── setup.ts
│ ├── test-enhanced-parsing.js
│ └── unit
│ ├── conversation-manager.test.ts
│ ├── semantic-analyzer-three-tier.test.ts
│ └── unified-parsing-system.test.ts
├── tsconfig.json
└── tsconfig.test.json
```
# Files
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-engine/core/engine.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Consolidated Prompt Engine - Unified Execution Tool
*
* Consolidates all prompt execution functionality into a single systematic tool:
* - execute_prompt (from index.ts)
* - Chain execution with progress tracking
* - Structural execution mode detection
* - Gate validation and retry logic
*/
import path from "path";
import { z } from "zod";
import { ConfigManager } from "../../../config/index.js";
import { Logger } from "../../../logging/index.js";
import { PromptManager } from "../../../prompts/index.js";
import {
ChainExecutionProgress,
ConvertedPrompt,
ExecutionState,
GateDefinition,
PromptData,
ToolResponse,
} from "../../../types/index.js";
// Import enhanced gate configuration from execution types
import {
type EnhancedGateConfiguration,
} from "../../../execution/types.js";
// REMOVED: ModularChainDefinition from deleted chain-scaffolding.ts
import {
PromptError,
ValidationError,
getAvailableTools,
isChainPrompt,
handleError as utilsHandleError,
} from "../../../utils/index.js";
import { processTemplate } from "../../../utils/jsonUtils.js";
// Gate evaluation removed - now using Framework methodology validation
import { FrameworkManager } from "../../../frameworks/framework-manager.js";
import { FrameworkExecutionContext } from "../../../frameworks/types/index.js";
import { FrameworkStateManager } from "../../../frameworks/framework-state-manager.js";
import { ContentAnalyzer } from "../../../semantic/configurable-semantic-analyzer.js";
import { ConversationManager } from "../../../text-references/conversation.js";
import { TextReferenceManager } from "../../../text-references/index.js";
import { ChainSessionManager, createChainSessionManager } from "../../../chain-session/manager.js";
import { createExecutionResponse } from "../../shared/structured-response-builder.js";
// Legacy gate system removed - using lightweight gates only
// NEW: Lightweight gate system
import {
LightweightGateSystem,
createLightweightGateSystem,
type TemporaryGateRegistryDefinition as TemporaryGateDefinition,
} from "../../../gates/core/index.js";
// NEW: Role-based gate components (Phase 3)
import {
GateGuidanceRenderer,
createGateGuidanceRenderer,
} from "../../../gates/guidance/GateGuidanceRenderer.js";
// Gate validation integration
import {
EngineValidator,
GateValidationResult,
} from "../utils/validation.js";
// Phase 4: Clean architecture gate intelligence (replaced advanced orchestrator)
import {
GateSelectionEngine,
createGateSelectionEngine,
ExtendedGateSelectionCriteria,
} from "../../../gates/intelligence/GateSelectionEngine.js";
import {
GateSelectionResult,
} from "../../../gates/core/gate-definitions.js";
// Phase 1: Intelligent category detection
import {
CategoryExtractor,
extractPromptCategory,
CategoryExtractionResult
} from "../utils/category-extractor.js";
// Phase 3: Prompt guidance system integration
import {
PromptGuidanceService,
createPromptGuidanceService,
type ServicePromptGuidanceResult
} from "../../../frameworks/prompt-guidance/index.js";
// REMOVED: ChainOrchestrator and detectChainType/isModularChain - modular chain system completely removed
// REMOVED: Chain URI addressing system - deprecated with markdown-embedded chains
// New unified parsing system
import {
createParsingSystem,
type ExecutionContext,
type ParsingSystem,
} from "../../../execution/parsers/index.js";
// REMOVED: Dynamic template discovery - scaffolding system deprecated
// Tool description manager
import { ToolDescriptionManager } from "../../tool-description-manager.js";
// Chain execution separation
import { ChainExecutor } from "./executor.js";
import { ChainExecutionContext, ChainExecutionOptions } from "./types.js";
// Enhanced tool dependencies removed (Phase 1.3) - Core implementations
// Simple core response handling without enhanced complexity
interface SimpleResponseFormatter {
formatResponse(content: any): any;
formatPromptEngineResponse(response: any, ...args: any[]): any; // Required
formatErrorResponse(error: any, ...args: any[]): any; // Required
setAnalyticsService(service: any): void; // Required
}
function createSimpleResponseFormatter(): SimpleResponseFormatter {
return {
formatResponse: (content: any) => content,
formatPromptEngineResponse: (response: any, ...args: any[]) => {
// Create proper ToolResponse with structuredContent using shared builder
const executionContext = args[0] || {};
const options = args[1] || {};
// For template/prompt execution, return simple text so Claude Code can see instructions
// For chain execution, keep structured content for state tracking
const executionType = executionContext.executionType || "prompt";
const includeStructuredContent = executionType === "chain";
return createExecutionResponse(
String(response),
"execute",
{
executionType,
executionTime: executionContext.executionTime,
frameworkUsed: executionContext.frameworkUsed,
stepsExecuted: executionContext.stepsExecuted,
sessionId: executionContext.sessionId,
gateResults: executionContext.gateResults
},
includeStructuredContent
);
},
formatErrorResponse: (error: any, ...args: any[]) => {
return createExecutionResponse(
String(error),
"error",
{
executionType: "prompt",
executionTime: 0,
frameworkUsed: undefined,
stepsExecuted: 0,
sessionId: undefined
}
);
},
setAnalyticsService: (service: any) => {}, // No-op for now
};
}
// Simple output schema (minimal for Phase 1)
const promptEngineOutputSchema = {
content: { type: "array" },
isError: { type: "boolean", optional: true },
};
// Type aliases for compatibility
type ResponseFormatter = SimpleResponseFormatter;
const createResponseFormatter = createSimpleResponseFormatter;
type FormatterExecutionContext = {
[key: string]: any; // Completely flexible for Phase 1
};
// Analytics service
import { ExecutionData, MetricsCollector } from "../../../metrics/index.js";
/**
* Prompt classification interface for execution strategy
*/
export interface PromptClassification {
executionType: "prompt" | "template" | "chain";
requiresExecution: boolean;
confidence: number;
reasoning: string[];
suggestedGates: string[];
framework?: string;
}
/**
* Tool routing detection result interface
*/
interface ToolRoutingResult {
requiresRouting: boolean;
targetTool?: string;
translatedParams?: Record<string, any>;
originalCommand?: string;
}
/**
* Consolidated Prompt Engine Tool
*/
export class ConsolidatedPromptEngine {
private logger: Logger;
private mcpServer: any;
private promptManager: PromptManager;
private configManager: ConfigManager;
private readonly serverRoot: string;
private semanticAnalyzer: ContentAnalyzer;
private conversationManager: ConversationManager;
private textReferenceManager: TextReferenceManager;
private chainSessionManager: ChainSessionManager;
private frameworkStateManager?: FrameworkStateManager;
private frameworkManager?: FrameworkManager;
// Legacy gate system removed - using only lightweightGateSystem
// NEW: Lightweight gate system (Phase 2 integration)
private lightweightGateSystem: LightweightGateSystem;
// NEW: Temporary gate registry access (Phase 3 enhancement)
private get temporaryGateRegistry() {
return this.lightweightGateSystem.getTemporaryGateRegistry?.();
}
// NEW: Role-based gate guidance renderer (Phase 3)
private gateGuidanceRenderer: GateGuidanceRenderer;
// Gate validation engine
private engineValidator?: EngineValidator;
// Phase 4: Clean architecture gate intelligence
private gateSelectionEngine?: GateSelectionEngine;
// Chain execution delegation
private chainExecutor?: ChainExecutor;
// REMOVED: chainOrchestrator - modular chain system removed
// Chain URI addressing system
// REMOVED: chainAddressingSystem - deprecated with markdown-embedded chains
// MCP Tools Manager reference for analytics flow
private mcpToolsManager?: any;
// Analytics service for event-driven analytics collection
private analyticsService?: MetricsCollector;
// Response formatter for structured output
private responseFormatter: ResponseFormatter;
// New unified parsing system
private parsingSystem: ParsingSystem;
// Dynamic template discovery system
// REMOVED: dynamicTemplateDiscovery - scaffolding system deprecated
// Tool description manager
private toolDescriptionManager?: ToolDescriptionManager;
// Phase 3: Prompt guidance service
private promptGuidanceService?: PromptGuidanceService;
private activeGateRequest?: {
gateIds: string[];
gateMode: 'enforce' | 'advise' | 'report';
qualityGates: string[];
customChecks: Array<{ name: string; description: string }>;
executionScopeId?: string;
};
// Data references
private promptsData: PromptData[] = [];
private convertedPrompts: ConvertedPrompt[] = [];
// Execution state tracking
private currentExecutionState: ExecutionState | null = null;
private executionHistory: ExecutionState[] = [];
private chainProgressState: ChainExecutionProgress | null = null;
constructor(
logger: Logger,
mcpServer: any,
promptManager: PromptManager,
configManager: ConfigManager,
semanticAnalyzer: ContentAnalyzer,
conversationManager: ConversationManager,
textReferenceManager: TextReferenceManager,
// Legacy gateEvaluationService parameter removed - using lightweight system only
mcpToolsManager?: any
// Phase 3: Removed executionCoordinator parameter - no longer needed
) {
this.logger = logger;
this.mcpServer = mcpServer;
this.promptManager = promptManager;
this.configManager = configManager;
this.semanticAnalyzer = semanticAnalyzer;
this.conversationManager = conversationManager;
this.textReferenceManager = textReferenceManager;
// Initialize chain session manager with both conversation and text reference managers
this.chainSessionManager = createChainSessionManager(logger, conversationManager, textReferenceManager);
// Legacy gate evaluation service assignment removed
this.mcpToolsManager = mcpToolsManager;
// Phase 3: Removed executionCoordinator assignment - using LLM-driven chain model
// Initialize lightweight gate system with temporary gates (Phase 3 enhancement)
const config = configManager.getConfig();
const gatesConfig = config.gates;
const configRoot =
typeof this.configManager.getServerRoot === 'function'
? this.configManager.getServerRoot()
: path.dirname(this.configManager.getConfigPath?.() ?? path.join(process.cwd(), 'config.json'));
this.serverRoot = configRoot;
const gatesDirectory = gatesConfig?.definitionsDirectory
? path.isAbsolute(gatesConfig.definitionsDirectory)
? gatesConfig.definitionsDirectory
: path.resolve(configRoot, gatesConfig.definitionsDirectory)
: path.resolve(configRoot, 'src/gates/definitions');
// Get LLM config for gate validator
const llmConfig = config.analysis?.semanticAnalysis?.llmIntegration;
this.lightweightGateSystem = createLightweightGateSystem(
logger,
gatesDirectory,
undefined, // gateSystemManager - will be set later if needed
{
enableTemporaryGates: true,
maxMemoryGates: 100, // Allow up to 100 temporary gates in memory
defaultExpirationMs: 30 * 60 * 1000, // 30 minutes default expiration
llmConfig // Pass LLM config to gate validator
}
);
// NEW: Initialize role-based gate guidance renderer (Phase 3)
// Phase 3 Enhancement: Pass temporary gate registry to renderer for temp gate support
const temporaryGateRegistry = this.lightweightGateSystem.getTemporaryGateRegistry();
this.gateGuidanceRenderer = createGateGuidanceRenderer(
logger,
gatesDirectory,
temporaryGateRegistry
);
// Initialize EngineValidator with gate system (Phase 1.1 fix)
this.engineValidator = new EngineValidator(this.lightweightGateSystem);
// Phase 4: Initialize clean architecture gate intelligence
this.gateSelectionEngine = createGateSelectionEngine(logger);
// Note: Performance analytics now handled separately through system control
// No need to connect gate selection engine to other components
// Initialize new parsing system
this.parsingSystem = createParsingSystem(logger);
// Initialize dynamic template discovery
// REMOVED: Dynamic template discovery initialization - scaffolding system deprecated
// Initialize response formatter
this.responseFormatter = createResponseFormatter();
this.logger.info(
"ConsolidatedPromptEngine initialized with new unified parsing system, dynamic template discovery, and response formatter"
);
}
/**
* Update data references
*/
updateData(
promptsData: PromptData[],
convertedPrompts: ConvertedPrompt[]
): void {
this.promptsData = promptsData;
this.convertedPrompts = convertedPrompts;
}
/**
* Set framework state manager (called after initialization)
*/
setFrameworkStateManager(frameworkStateManager: FrameworkStateManager): void {
this.frameworkStateManager = frameworkStateManager;
this.initializeChainExecutor();
}
/**
* Set framework manager (called after initialization)
*/
setFrameworkManager(frameworkManager: FrameworkManager): void {
this.frameworkManager = frameworkManager;
this.initializeChainExecutor();
this.initializePromptGuidanceService();
}
/**
* Initialize ChainExecutor once dependencies are available
*/
private initializeChainExecutor(): void {
if (this.frameworkManager && this.frameworkStateManager) {
this.chainExecutor = new ChainExecutor(
this.conversationManager,
this.lightweightGateSystem,
this.frameworkManager,
this.frameworkStateManager,
this.responseFormatter,
this.chainSessionManager
);
this.logger.debug("ChainExecutor initialized successfully");
}
}
/**
* Initialize PromptGuidanceService once framework manager is available
*/
private async initializePromptGuidanceService(): Promise<void> {
if (this.frameworkManager && !this.promptGuidanceService) {
try {
const methodologyStatePath = path.join(
this.serverRoot,
'runtime-state',
'framework-state.json'
);
this.promptGuidanceService = await createPromptGuidanceService(
this.logger,
{
systemPromptInjection: {
enabled: true,
injectionMethod: 'smart',
enableTemplateVariables: true,
enableContextualEnhancement: true
},
templateEnhancement: {
enabled: true,
enhancementLevel: 'moderate',
enableArgumentSuggestions: true,
enableStructureOptimization: true
},
methodologyTracking: {
enabled: true,
persistStateToDisk: true,
enableHealthMonitoring: true,
stateFilePath: methodologyStatePath
}
},
this.frameworkManager
);
this.logger.debug("PromptGuidanceService initialized successfully");
} catch (error) {
this.logger.warn("Failed to initialize PromptGuidanceService:", error);
// Continue without guidance service - it's optional
}
}
}
/**
* Set analytics service (called after initialization)
*/
setAnalyticsService(analyticsService: MetricsCollector): void {
this.analyticsService = analyticsService;
this.responseFormatter.setAnalyticsService(analyticsService);
}
/**
* Set tool description manager (called after initialization)
*/
setToolDescriptionManager(manager: ToolDescriptionManager): void {
this.toolDescriptionManager = manager;
}
/**
* Get the prompts base path using ConfigManager for cross-platform compatibility
*/
private getPromptsBasePath(): string {
// Use environment variable override if available
if (process.env.MCP_PROMPTS_PATH) {
return process.env.MCP_PROMPTS_PATH;
}
// Use ConfigManager to get proper path resolution
const promptsFilePath = this.configManager.getPromptsFilePath();
// Get the directory containing the prompts config file
return path.dirname(promptsFilePath);
}
// REMOVED: setChainOrchestrator method - modular chain system removed
/**
* Get lightweight gate system for external access
*/
getLightweightGateSystem(): LightweightGateSystem {
return this.lightweightGateSystem;
}
/**
* Expose gate guidance renderer for discovery operations
*/
getGateGuidanceRenderer(): GateGuidanceRenderer {
return this.gateGuidanceRenderer;
}
/**
* Set gate system manager for runtime gate management
*/
setGateSystemManager(gateSystemManager: any): void {
this.lightweightGateSystem.setGateSystemManager(gateSystemManager);
this.logger.debug("Gate system manager configured for prompt engine");
}
/**
* Get framework-enhanced system prompt injection
*/
private async getFrameworkExecutionContext(
prompt: ConvertedPrompt
): Promise<FrameworkExecutionContext | null> {
this.logger.debug(`[ENGINE DEBUG] getFrameworkExecutionContext called for prompt: ${prompt.id}`);
if (!this.frameworkManager || !this.frameworkStateManager) {
this.logger.debug(`[ENGINE DEBUG] Missing dependencies - frameworkManager: ${!!this.frameworkManager}, frameworkStateManager: ${!!this.frameworkStateManager}`);
return null;
}
// NEW: Check if framework system is enabled before generating context
const isEnabled = this.frameworkStateManager.isFrameworkSystemEnabled();
this.logger.debug(`[ENGINE DEBUG] Framework system enabled: ${isEnabled}`);
if (!isEnabled) {
return null;
}
try {
// Get current active framework from state manager
const activeFramework = this.frameworkStateManager.getActiveFramework();
this.logger.debug(`[ENGINE DEBUG] Active framework:`, {
methodology: activeFramework.methodology,
name: activeFramework.name
});
// Generate execution context using the framework manager
const context = this.frameworkManager.generateExecutionContext(prompt, {
userPreference: activeFramework.methodology as any,
});
this.logger.debug(`[ENGINE DEBUG] Generated execution context:`, {
hasContext: !!context,
contextType: context ? typeof context : 'null',
hasSystemPrompt: context?.systemPrompt ? true : false,
systemPromptLength: context?.systemPrompt?.length || 0
});
return context;
} catch (error) {
this.logger.warn(
"Failed to generate framework execution context:",
error
);
return null;
}
}
/**
* Main prompt execution handler
*/
public async executePromptCommand(
args: {
command: string;
execution_mode?: "auto" | "prompt" | "template" | "chain";
gate_validation?: boolean;
step_confirmation?: boolean;
llm_driven_execution?: boolean;
force_restart?: boolean;
session_id?: string;
chain_uri?: string;
timeout?: number;
options?: Record<string, any>;
temporary_gates?: TemporaryGateDefinition[];
gate_scope?: 'execution' | 'session' | 'chain' | 'step';
inherit_chain_gates?: boolean;
quality_gates?: string[];
custom_checks?: Array<{ name: string; description: string }>;
gate_mode?: 'enforce' | 'advise' | 'report';
},
extra: any
): Promise<ToolResponse> {
const {
command,
execution_mode = "auto",
gate_validation,
step_confirmation,
llm_driven_execution,
force_restart,
session_id,
chain_uri,
timeout,
options = {},
temporary_gates,
gate_scope = 'execution',
inherit_chain_gates = true,
quality_gates,
custom_checks,
gate_mode,
} = args;
const hasSimplifiedGates =
(quality_gates?.length ?? 0) > 0 || (custom_checks?.length ?? 0) > 0;
const resolvedGateMode: 'enforce' | 'advise' | 'report' =
gate_mode ?? (hasSimplifiedGates ? 'enforce' : 'advise');
const normalizedArgs = {
...args,
gate_mode: resolvedGateMode,
quality_gates,
custom_checks,
};
this.logger.info(
`🚀 [ENTRY] Prompt Engine: Executing "${command}" (mode: ${execution_mode})`
);
// Phase 1: Check if command should be routed to a different tool
const routingResult = await this.detectToolRoutingCommand(command);
this.logger.info(`🔍 [ROUTING DEBUG] Tool routing check:`, {
command,
requiresRouting: routingResult.requiresRouting,
targetTool: routingResult.targetTool
});
if (routingResult.requiresRouting) {
this.logger.info(`🔀 [ROUTING DEBUG] Command being routed to different tool: ${routingResult.targetTool}`);
const routedResult = await this.routeToTool(
routingResult.targetTool!,
routingResult.translatedParams!,
routingResult.originalCommand!
);
return routedResult;
}
// Parse command and extract execution context
const executionContext = await this.parseAndPrepareExecution(command);
// Handle chain management commands
if (executionContext.isChainManagement && this.chainExecutor) {
return await this.chainExecutor.executeChainManagement(
executionContext.chainAction!,
executionContext.chainParameters || {},
options
);
}
// Determine execution strategy
const strategy = await this.determineExecutionStrategy(
executionContext.convertedPrompt,
execution_mode,
{
gate_validation,
quality_gates,
custom_checks,
}
);
// Initialize execution state with session tracking
this.initializeExecutionState(
executionContext.convertedPrompt,
strategy,
session_id
);
// Execute using determined strategy
return await this.executeWithStrategy(strategy, executionContext, {
...normalizedArgs,
gate_validation,
step_confirmation,
llm_driven_execution,
force_restart,
session_id,
chain_uri,
timeout,
options,
});
}
/**
* Parse command and prepare execution context
*/
private async parseAndPrepareExecution(command: string) {
const {
promptId,
arguments: promptArgs,
convertedPrompt,
isChainManagement,
chainAction,
chainParameters,
} = await this.parseCommandUnified(command);
// Apply prompt guidance if available and not a chain management command
let enhancedPrompt = convertedPrompt;
let guidanceResult: ServicePromptGuidanceResult | undefined;
// FIXED: Re-enable PromptGuidanceService with system prompt injection only
// This provides framework methodology reminder at the START of responses
// Gate guidance (framework-compliance) provides quality criteria at the END
if (!isChainManagement && this.promptGuidanceService && convertedPrompt) {
try {
this.logger.info(`🔧 [FRAMEWORK DEBUG] Calling PromptGuidanceService for ${convertedPrompt.id}`, {
hasPromptGuidanceService: !!this.promptGuidanceService,
isInitialized: this.promptGuidanceService.isInitialized(),
originalSystemMessage: convertedPrompt.systemMessage?.substring(0, 100)
});
guidanceResult = await this.promptGuidanceService.applyGuidance(convertedPrompt, {
includeSystemPromptInjection: true, // ENABLED: Framework reminder at beginning
includeTemplateEnhancement: false // DISABLED: Prevent template duplication
});
this.logger.info(`🔧 [FRAMEWORK DEBUG] PromptGuidanceService result:`, {
guidanceApplied: guidanceResult.guidanceApplied,
hasEnhancedPrompt: !!guidanceResult.enhancedPrompt,
enhancementsApplied: guidanceResult.metadata.enhancementsApplied,
enhancedSystemMessage: guidanceResult.enhancedPrompt?.systemMessage?.substring(0, 200)
});
if (guidanceResult.guidanceApplied && guidanceResult.enhancedPrompt) {
enhancedPrompt = guidanceResult.enhancedPrompt;
this.logger.info(`✅ [FRAMEWORK DEBUG] Prompt guidance applied: ${guidanceResult.metadata.enhancementsApplied.join(', ')}`);
} else {
this.logger.warn(`⚠️ [FRAMEWORK DEBUG] Guidance not applied - guidanceApplied=${guidanceResult.guidanceApplied}, hasEnhancedPrompt=${!!guidanceResult.enhancedPrompt}`);
}
} catch (error) {
this.logger.error("❌ [FRAMEWORK DEBUG] Prompt guidance failed:", error);
}
} else {
this.logger.warn(`⚠️ [FRAMEWORK DEBUG] Skipping PromptGuidanceService:`, {
isChainManagement,
hasService: !!this.promptGuidanceService,
hasPrompt: !!convertedPrompt
});
}
return {
promptId,
promptArgs,
convertedPrompt: enhancedPrompt,
originalPrompt: convertedPrompt,
guidanceResult,
isChainManagement,
chainAction,
chainParameters,
};
}
/**
* Determine the execution strategy based on mode and prompt type
*/
private async determineExecutionStrategy(
convertedPrompt: any,
execution_mode: string,
overrides?: {
gate_validation?: boolean;
quality_gates?: string[];
custom_checks?: Array<{ name: string; description: string }>;
}
): Promise<{
mode: "prompt" | "template" | "chain";
gateValidation: boolean;
}> {
let effectiveExecutionMode: "prompt" | "template" | "chain";
if (!execution_mode || execution_mode === "auto") {
const detectedMode = await this.detectExecutionMode(convertedPrompt);
effectiveExecutionMode = detectedMode as "prompt" | "template" | "chain";
} else {
effectiveExecutionMode = execution_mode as
| "prompt"
| "template"
| "chain";
}
const hasSimplifiedGates =
(overrides?.quality_gates?.length ?? 0) > 0 ||
(overrides?.custom_checks?.length ?? 0) > 0;
const effectiveGateValidation =
overrides?.gate_validation ??
(hasSimplifiedGates ? true : effectiveExecutionMode === "chain");
this.logger.info(
`🔍 EXECUTION MODE DEBUG: Effective settings: mode=${effectiveExecutionMode}, gates=${effectiveGateValidation}, prompt=${convertedPrompt.id}, simplifiedGates=${hasSimplifiedGates}`
);
return {
mode: effectiveExecutionMode,
gateValidation: effectiveGateValidation,
};
}
/**
* Initialize execution state tracking with session support
*/
private initializeExecutionState(
convertedPrompt: any,
strategy: { mode: string; gateValidation: boolean },
sessionId?: string
) {
this.currentExecutionState = {
type: isChainPrompt(convertedPrompt) ? "chain" : "single",
promptId: convertedPrompt.id,
status: "pending",
gates: [],
results: {},
metadata: {
startTime: Date.now(),
executionMode: strategy.mode as "prompt" | "template" | "chain",
gateValidation: strategy.gateValidation,
sessionId, // Store session ID for step result capture
},
};
}
/**
* Execute using the determined strategy
*/
private async executeWithStrategy(
strategy: {
mode: "prompt" | "template" | "chain";
gateValidation: boolean;
},
context: any,
args: any
): Promise<ToolResponse> {
const { convertedPrompt, promptArgs } = context;
// Phase 3: Create execution scope for temporary gates
const executionScopeId = this.createExecutionScope(convertedPrompt, strategy, args);
try {
switch (strategy.mode) {
case "prompt":
this.logger.info(
`📍 EXECUTION PATH: Taking PROMPT path for ${convertedPrompt.id}`
);
const promptResult = await this.executePrompt(
convertedPrompt,
promptArgs,
this.getExecutionContext(executionScopeId, 'execution')
);
return promptResult;
case "template":
this.logger.info(
`📍 EXECUTION PATH: Taking TEMPLATE path for ${convertedPrompt.id}`
);
const templateResult = await this.executeTemplateWithFramework(
convertedPrompt,
promptArgs,
strategy.gateValidation,
this.getExecutionContext(executionScopeId, 'execution')
);
return templateResult;
case "chain":
this.logger.info(
`📍 EXECUTION PATH: Taking CHAIN path for ${convertedPrompt.id}`
);
if (!this.chainExecutor) {
return this.responseFormatter.formatErrorResponse(
'ChainExecutor not initialized - framework managers required',
'ConsolidatedPromptEngine',
'executePromptCommand'
);
}
// Ensure chain session exists
const chainSessionId = await this.ensureChainSession(
convertedPrompt,
args.session_id,
args.force_restart,
promptArgs
);
return await this.chainExecutor.executeChainWithDualSupport(
convertedPrompt,
promptArgs,
strategy.gateValidation,
{
enableGates: strategy.gateValidation,
force_restart: args.force_restart,
session_id: chainSessionId,
step_confirmation: args.step_confirmation,
llm_driven_execution: args.llm_driven_execution,
chain_uri: args.chain_uri,
timeout: args.timeout,
temporary_gates: args.temporary_gates,
gate_scope: args.gate_scope,
inherit_chain_gates: args.inherit_chain_gates,
...args.options,
}
);
default:
throw new ValidationError(`Unknown execution mode: ${strategy.mode}`);
}
} finally {
// Phase 3: Cleanup execution scope and temporary gates
this.cleanupExecutionScope(executionScopeId);
}
}
/**
* Phase 3: Create execution scope for temporary gate lifecycle management
* Phase 4: Enhanced with execution-time temporary gate support
*/
private createExecutionScope(
convertedPrompt: any,
strategy: { mode: string; gateValidation: boolean },
args: any
): string {
const scopeId = `exec_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
this.logger.info(`🔧 [EXECUTION SCOPE] Created execution scope:`, {
scopeId,
promptId: convertedPrompt?.id,
mode: strategy.mode,
gateValidation: strategy.gateValidation,
sessionId: args.session_id,
hasExecutionTimeGates: !!args.temporary_gates,
executionTimeGateCount: args.temporary_gates?.length || 0
});
// Create execution-time temporary gates if provided
if (args.temporary_gates && args.temporary_gates.length > 0 && this.temporaryGateRegistry) {
const gateScope = args.gate_scope || 'execution';
this.logger.info(`🚀 [EXECUTION-TIME GATES] Creating ${args.temporary_gates.length} execution-time temporary gates`, {
scope: gateScope,
scopeId
});
for (const tempGate of args.temporary_gates) {
try {
const gateId = this.temporaryGateRegistry.createTemporaryGate(
{
name: tempGate.name,
type: tempGate.type,
scope: gateScope,
description: tempGate.description,
guidance: tempGate.guidance,
pass_criteria: tempGate.pass_criteria,
source: 'manual',
context: { executionTimeGate: true, promptId: convertedPrompt?.id }
},
scopeId
);
this.logger.debug(`✅ [EXECUTION-TIME GATES] Created temporary gate: ${gateId} (${tempGate.name})`);
} catch (error) {
this.logger.error(`❌ [EXECUTION-TIME GATES] Failed to create temporary gate:`, {
error: error instanceof Error ? error.message : String(error),
gateName: tempGate.name
});
}
}
}
const simplifiedGateIds = this.convertSimplifiedGates(
args.quality_gates,
args.custom_checks,
scopeId
);
const hasSimplifiedGates =
(args.quality_gates?.length ?? 0) > 0 ||
(args.custom_checks?.length ?? 0) > 0;
if (hasSimplifiedGates || args.gate_mode) {
const gateMode = (args.gate_mode as 'enforce' | 'advise' | 'report') || 'advise';
this.activeGateRequest = {
gateIds: simplifiedGateIds,
gateMode,
qualityGates: args.quality_gates || [],
customChecks: args.custom_checks || [],
executionScopeId: scopeId,
};
} else {
this.activeGateRequest = undefined;
}
return scopeId;
}
/**
* Phase 3: Cleanup execution scope and associated temporary gates
*/
private cleanupExecutionScope(scopeId: string): void {
if (this.temporaryGateRegistry) {
this.temporaryGateRegistry.cleanupScope(scopeId);
this.logger.info(`🧹 [EXECUTION SCOPE] Cleaned up execution scope: ${scopeId}`);
} else {
this.logger.debug(`🧹 [EXECUTION SCOPE] No temporary gate registry available for cleanup: ${scopeId}`);
}
if (this.activeGateRequest?.executionScopeId === scopeId) {
this.activeGateRequest = undefined;
}
}
private convertSimplifiedGates(
qualityGates?: string[],
customChecks?: Array<{ name: string; description: string }>,
executionScopeId?: string
): string[] {
const gateIds: string[] = [];
if (qualityGates && qualityGates.length > 0) {
gateIds.push(...qualityGates);
}
if (customChecks && customChecks.length > 0) {
if (!this.temporaryGateRegistry) {
this.logger.warn(
"Temporary gate registry unavailable; custom checks cannot be registered"
);
} else {
for (const check of customChecks) {
try {
const gateId = this.temporaryGateRegistry.createTemporaryGate(
{
name: check.name,
type: 'validation',
scope: 'execution',
description: check.description,
guidance: `Ensure: ${check.description}`,
pass_criteria: [],
source: 'manual',
},
executionScopeId
);
gateIds.push(gateId);
} catch (error) {
this.logger.error(
`Failed to create temporary gate for custom check ${check.name}:`,
error
);
}
}
}
}
return gateIds;
}
private mergeRequestedGates(gates: string[]): string[] {
const requested = this.activeGateRequest?.gateIds || [];
if (!requested.length) {
return gates;
}
const combined = [...requested, ...gates];
return [...new Set(combined)];
}
private formatGateStatus(validation: GateValidationResult | null): string {
if (!validation) {
if (this.activeGateRequest?.gateMode === 'report') {
return `\n\n---\nℹ️ **Quality Gates**: Validation not executed\n`;
}
return '';
}
const total = validation.results?.length ?? 0;
if (validation.passed) {
return `\n\n---\n✅ **Quality Gates**: All checks passed (${total} gates)\n`;
}
const failed = (validation.results || []).filter((result) => !result.passed);
let message = `\n\n---\n⚠️ **Quality Gates**: ${failed.length} of ${total} failed\n\n`;
for (const result of failed) {
message += `❌ **${result.gate}**: ${result.message}\n`;
}
return message;
}
/**
* Phase 3: Get execution context for temporary gates
*/
private getExecutionContext(scopeId: string, scope: 'execution' | 'session' | 'chain' | 'step' = 'execution') {
return {
scopeId,
scope
};
}
/**
* Phase 3: Extract temporary gates from prompt configuration
*/
private getTemporaryGatesFromPrompt(prompt: ConvertedPrompt): Array<Omit<TemporaryGateDefinition, 'id' | 'created_at'>> | undefined {
// Phase 3 Fix: Check enhancedGateConfiguration first, then fall back to gateConfiguration
const gateConfig = (prompt.enhancedGateConfiguration || prompt.gateConfiguration) as EnhancedGateConfiguration | undefined;
if (!gateConfig?.temporary_gates) {
return undefined;
}
return gateConfig.temporary_gates.map((tempGate: any) => ({
name: tempGate.name,
type: tempGate.type,
scope: tempGate.scope,
description: tempGate.description,
guidance: tempGate.guidance,
pass_criteria: tempGate.pass_criteria,
expires_at: tempGate.expires_at,
source: tempGate.source || 'manual',
context: tempGate.context
}));
}
/**
* Phase 1: Chain Management Command Detection
*/
// REMOVED: detectChainManagementCommand - migrated to ChainExecutor
// REMOVED: parseKeyValueParams - migrated to ChainExecutor
// REMOVED: handleChainManagementCommand - migrated to ChainExecutor
/**
* Detect if command should be routed to a different tool
*/
private async detectToolRoutingCommand(command: string): Promise<ToolRoutingResult> {
const trimmedCommand = command.trim();
// Built-in commands that route to prompt_manager
if (/^(>>|\/)?listprompts?(\s.*)?$/i.test(trimmedCommand)) {
const args = trimmedCommand.replace(/^(>>|\/)?listprompts?\s*/i, '').trim();
return {
requiresRouting: true,
targetTool: 'prompt_manager',
translatedParams: {
action: 'list',
...(args && { search_query: args })
},
originalCommand: command
};
}
// Help and status commands that route to system_control
if (/^(>>|\/)?help$/i.test(trimmedCommand)) {
return {
requiresRouting: true,
targetTool: 'system_control',
translatedParams: {
action: 'status',
show_details: true
},
originalCommand: command
};
}
if (/^(>>|\/)?status$/i.test(trimmedCommand)) {
return {
requiresRouting: true,
targetTool: 'system_control',
translatedParams: {
action: 'status'
},
originalCommand: command
};
}
// Framework switch commands
const frameworkMatch = trimmedCommand.match(/^(>>|\/)?framework\s+(switch|change)\s+(.+)$/i);
if (frameworkMatch) {
return {
requiresRouting: true,
targetTool: 'system_control',
translatedParams: {
action: 'framework',
operation: 'switch',
framework: frameworkMatch[3].trim()
},
originalCommand: command
};
}
// Analytics/metrics commands
if (/^(>>|\/)?analytics?$/i.test(trimmedCommand)) {
return {
requiresRouting: true,
targetTool: 'system_control',
translatedParams: {
action: 'analytics'
},
originalCommand: command
};
}
// No routing needed - let existing parser handle it
return {
requiresRouting: false
};
}
/**
* Route command to appropriate tool with safe error handling
*/
private async routeToTool(targetTool: string, params: Record<string, any>, originalCommand: string): Promise<ToolResponse> {
this.logger.info(`🔀 Routing command "${originalCommand}" to ${targetTool}`);
try {
switch (targetTool) {
case 'prompt_manager':
if (this.mcpToolsManager?.promptManagerTool) {
this.logger.debug(`Calling prompt_manager with params:`, params);
return await this.mcpToolsManager.promptManagerTool.handleAction(params, {});
} else {
throw new Error('Prompt manager tool not available');
}
case 'system_control':
if (this.mcpToolsManager?.systemControl) {
this.logger.debug(`Calling system_control with params:`, params);
return await this.mcpToolsManager.systemControl.handleAction(params, {});
} else {
throw new Error('System control tool not available');
}
default:
throw new Error(`Unknown target tool: ${targetTool}`);
}
} catch (error) {
this.logger.error(`Tool routing failed for ${targetTool}:`, error);
// Return formatted error response
return this.responseFormatter.formatErrorResponse(
error instanceof Error
? `Tool routing failed: ${error.message}`
: `Tool routing failed: ${String(error)}`,
{
tool: 'prompt_engine',
operation: 'routeToTool',
targetTool,
originalCommand
},
{
includeStructuredData: true
}
);
}
}
/**
* Parse command string using unified parsing system with chain management detection
*/
private async parseCommandUnified(command: string): Promise<{
promptId: string;
arguments: Record<string, any>;
convertedPrompt: ConvertedPrompt;
isChainManagement?: boolean;
chainAction?: string;
chainParameters?: Record<string, any>;
}> {
// Phase 1: Smart chain management command detection
if (this.chainExecutor) {
const chainCommand = this.chainExecutor.detectChainManagementCommand(command);
if (chainCommand.isChainManagement) {
// Mark this as a chain management operation
return {
promptId: '',
arguments: {},
convertedPrompt: {} as ConvertedPrompt,
isChainManagement: true,
chainAction: chainCommand.action!,
chainParameters: chainCommand.parameters!
};
}
}
// Use new unified command parser
const parseResult = await this.parsingSystem.commandParser.parseCommand(
command,
this.promptsData
);
// Find the matching prompt data and converted prompt (case-insensitive lookup)
const promptData = this.promptsData.find(
(p) => p.id.toLowerCase() === parseResult.promptId.toLowerCase() ||
(p.name && p.name.toLowerCase() === parseResult.promptId.toLowerCase())
);
if (!promptData) {
throw new PromptError(
`Unknown prompt: ${parseResult.promptId}. Use >>listprompts to see available prompts.`
);
}
const convertedPrompt = this.convertedPrompts.find(
(p) => p.id === promptData.id
);
if (!convertedPrompt) {
throw new PromptError(
`Converted prompt data not found for: ${parseResult.promptId}`
);
}
// Process arguments using new argument processor
const context: ExecutionContext = {
conversationHistory: [], // Would be injected from conversation manager
environmentVars: process.env as Record<string, string>,
promptDefaults: {},
systemContext: {},
};
const argResult = await this.parsingSystem.argumentParser.parseArguments(
parseResult.rawArgs,
promptData,
context
);
// Log parsing details for monitoring
this.logger.debug(`Command parsed successfully:`, {
strategy: parseResult.metadata.parseStrategy,
confidence: parseResult.confidence,
argumentsProcessed: Object.keys(argResult.processedArgs).length,
appliedDefaults: argResult.metadata.appliedDefaults.length,
warnings: [
...parseResult.metadata.warnings,
...argResult.metadata.warnings,
],
});
return {
promptId: promptData.id,
arguments: argResult.processedArgs, // Pass typed arguments directly
convertedPrompt,
};
}
/**
* Detect execution mode using semantic analysis - THREE-TIER MODEL
* Returns appropriate execution strategy based on prompt characteristics
*/
private async detectExecutionMode(
convertedPrompt: ConvertedPrompt
): Promise<"prompt" | "template" | "chain"> {
if (convertedPrompt.executionMode) {
return convertedPrompt.executionMode;
}
const classification = await this.analyzePrompt(convertedPrompt);
this.autoAssignQualityGates(convertedPrompt, classification);
this.logger.debug(
`Semantic analysis: ${classification.executionType} (${Math.round(
classification.confidence * 100
)}%)`
);
// Return the semantic analysis result directly - it now handles the three-tier distinction
return classification.executionType;
}
/**
* Create fallback analysis when semantic analysis is disabled
*/
private createDisabledAnalysisFallback(
prompt: ConvertedPrompt
): PromptClassification {
const hasChainSteps = Boolean(prompt.chainSteps?.length);
const argCount = prompt.arguments?.length || 0;
const hasTemplateVars = /\{\{.*?\}\}/g.test(
prompt.userMessageTemplate || ""
);
// Reliable structural detection: only use verifiable indicators
const hasComplexTemplateLogic =
/\{\{.*?\|.*?\}\}|\{%-.*?-%\}|\{%.*?if.*?%\}|\{%.*?for.*?%\}/g.test(
prompt.userMessageTemplate || ""
);
const hasMultipleArgs = argCount > 1; // More than one argument suggests complexity
// Three-tier detection based on structural indicators only
let executionType: "prompt" | "template" | "chain" = "prompt";
if (hasChainSteps) {
executionType = "chain";
} else if (hasComplexTemplateLogic) {
// Complex Nunjucks logic always needs template mode
executionType = "template";
} else if (hasTemplateVars && hasMultipleArgs) {
// Template variables with multiple args suggests framework benefit
executionType = "template";
}
// Default to 'prompt' for simple cases (no vars, single arg, or static content)
return {
executionType,
requiresExecution: true,
confidence: 0.9, // High confidence in structural detection
reasoning: [
"Structural auto detection (semantic analysis disabled)",
`Args: ${argCount}, Template vars: ${hasTemplateVars}, Complex logic: ${hasComplexTemplateLogic}`,
`Selected ${executionType} mode based on verifiable structural indicators`,
],
suggestedGates: ["basic_validation"],
framework: "disabled",
};
}
/**
* Detect analysis intent using LLM semantic understanding (FUTURE IMPLEMENTATION)
*
* This method will be implemented when the LLM semantic layer is completed.
* It will provide intelligent analysis intent detection by examining:
* - Template content and complexity
* - Argument semantics and naming patterns
* - Task complexity indicators
* - Context and domain-specific signals
*
* @param prompt - The prompt to analyze for analysis intent
* @returns Promise<boolean> - True if prompt requires analytical framework processing
*
* @todo Implement when ContentAnalyzer LLM integration is enabled
* @todo Design proper interface for semantic intent classification
* @todo Add confidence scoring and reasoning for intent decisions
*/
private async detectAnalysisIntentLLM(
prompt: ConvertedPrompt
): Promise<boolean> {
// STUB: Always return false until LLM semantic analysis is implemented
// When implemented, this will use the LLM to intelligently detect:
// - Analysis vs formatting tasks
// - Complex reasoning requirements
// - Domain-specific analytical patterns
// - Context-dependent intent signals
this.logger.debug(
`LLM analysis intent detection not yet implemented for ${prompt.id}`
);
return false;
}
/**
* Analyze prompt for execution strategy (configuration-aware)
*/
private async analyzePrompt(
prompt: ConvertedPrompt
): Promise<PromptClassification> {
// Check if semantic analysis is enabled via the analyzer
if (!this.semanticAnalyzer.isLLMEnabled()) {
this.logger.debug(
`Semantic analysis disabled for ${prompt.id} - using structural fallback`
);
return this.createDisabledAnalysisFallback(prompt);
}
try {
const analysis = await this.semanticAnalyzer.analyzePrompt(prompt);
return {
executionType: analysis.executionType,
requiresExecution: analysis.requiresExecution,
confidence: analysis.confidence,
reasoning: analysis.reasoning,
suggestedGates: analysis.suggestedGates,
framework: "semantic",
};
} catch (error) {
this.logger.error(`Semantic analysis failed for ${prompt.id}:`, error);
return {
executionType: isChainPrompt(prompt) ? "chain" : "template",
requiresExecution: true,
confidence: 0.5,
reasoning: [`Fallback analysis: ${error}`],
suggestedGates: ["execution_validation"],
framework: "fallback",
};
}
}
/**
* Auto-assign quality gates based on classification
*/
private autoAssignQualityGates(
prompt: ConvertedPrompt,
classification: PromptClassification
): void {
const autoGates: GateDefinition[] = [];
if (classification.requiresExecution && classification.confidence > 0.5) {
autoGates.push({
id: "content_length_validation",
name: "Content Length Validation",
type: "validation",
requirements: [
{
type: "content_length",
criteria: { min: 50 },
required: true,
},
],
failureAction: "retry",
});
}
if (autoGates.length > 0) {
(prompt as any).autoAssignedGates = autoGates;
this.logger.debug(
`Auto-assigned ${autoGates.length} gates for ${prompt.id}`
);
}
}
/**
* NEW: Execute basic prompt with simple variable substitution (fastest)
* No framework processing, minimal overhead
*/
private async executePrompt(
prompt: ConvertedPrompt,
args: Record<string, string>,
executionContext?: {
scopeId?: string;
scope?: 'execution' | 'session' | 'chain' | 'step';
}
): Promise<ToolResponse> {
if (!this.currentExecutionState) {
throw new PromptError("No execution state available");
}
this.currentExecutionState.status = "running";
// Simple template processing without framework enhancement
let content = prompt.userMessageTemplate;
if (prompt.systemMessage) {
content = `[System: ${prompt.systemMessage}]\n\n${content}`;
}
// Phase 4: Enhanced args without gate injection (gates now appended at end)
const enhancedArgs = args;
// Phase 3: Inject session context for step result interpolation
const sessionEnhancedArgs = await this.injectSessionContext(enhancedArgs);
// Fast variable substitution using modern template processor
content = processTemplate(content, sessionEnhancedArgs, {});
// Phase 4: Enhanced gate validation for basic prompts (only when framework system is enabled)
let gateResults: GateValidationResult | null = null;
const frameworkEnabled = this.frameworkStateManager?.isFrameworkSystemEnabled();
const hasRequestedGates = (this.activeGateRequest?.gateIds?.length || 0) > 0;
const shouldValidate = frameworkEnabled || hasRequestedGates;
this.logger.info(
`🔍 [DEBUG] Framework system enabled: ${frameworkEnabled}, requestedGates=${hasRequestedGates}`
);
if (shouldValidate) {
const gateValidation = await this.validateContentWithGates(prompt, content, sessionEnhancedArgs, 'prompt');
gateResults = gateValidation.validation;
this.logger.info(`🔍 [DEBUG] Gate validation result:`, {
hasGateResults: !!gateResults,
gateResultsType: typeof gateResults,
gateResultsValue: gateResults
});
if (gateResults && !gateResults.passed) {
this.logger.debug(`Basic prompt gate validation failed for ${prompt.id}:`, gateResults.results);
// For basic prompts, we just log and continue
} else if (gateResults && gateResults.passed) {
this.logger.debug(`Basic prompt gate validation passed for ${prompt.id}`);
}
}
// Update state and analytics
this.currentExecutionState.status = "completed";
this.currentExecutionState.metadata.endTime = Date.now();
// Store gate results in execution state for analytics
if (gateResults) {
(this.currentExecutionState.metadata as any).gateResults = gateResults;
}
// Capture step result if this is part of a chain session
await this.captureStepResult(content, prompt);
this.recordExecutionAnalytics();
// Create execution context for response formatter
const executionId = `exec_${Date.now()}_${Math.random()
.toString(36)
.substr(2, 9)}`;
const activeFramework =
this.frameworkStateManager?.getActiveFramework()?.name;
const frameworkEnabledForContext =
this.frameworkStateManager?.isFrameworkSystemEnabled() || false;
const formatterContext: FormatterExecutionContext = {
executionId,
executionType: "prompt",
startTime: this.currentExecutionState.metadata.startTime,
endTime: this.currentExecutionState.metadata.endTime || Date.now(),
frameworkUsed: activeFramework,
frameworkEnabled: frameworkEnabledForContext,
success: true,
};
// FIXED: Add supplemental gate guidance for prompt mode (same as template mode)
let enhancedContent = content;
this.logger.info(`🔍 [DEBUG] Gate conditional logic:`, {
hasGateResults: !!gateResults,
gateResultsValue: gateResults,
willExecuteIfBranch: !!gateResults,
willExecuteElseBranch: !gateResults
});
if (gateResults) {
this.logger.info(`🔀 [DEBUG] Taking IF branch (gateResults exists)`);
// Get selected gates from validation - basic prompts use 'prompt' mode gates
const selectedGates = await this.getAdvancedGateSelection(prompt, 'prompt');
const frameworkContext = await this.getFrameworkExecutionContext(prompt);
if (selectedGates.length > 0) {
const temporaryGates = this.getTemporaryGatesFromPrompt(prompt);
const supplementalGuidance = await this.getSupplementalGateGuidance(
selectedGates,
frameworkContext,
prompt,
temporaryGates,
executionContext
);
if (supplementalGuidance) {
enhancedContent = content + supplementalGuidance;
}
}
} else {
this.logger.info(`🔀 [DEBUG] Taking ELSE branch (no gateResults) - this should call our gate guidance renderer`);
// TEMP TEST: Force gate guidance even without validation results
const testGates = ['framework-compliance', 'educational-clarity'];
const frameworkContext = await this.getFrameworkExecutionContext(prompt);
const temporaryGates = this.getTemporaryGatesFromPrompt(prompt);
const supplementalGuidance = await this.getSupplementalGateGuidance(
testGates,
frameworkContext,
prompt,
temporaryGates,
executionContext
);
if (supplementalGuidance) {
enhancedContent = content + supplementalGuidance;
} else {
enhancedContent = content + "(Gate manager returned empty guidance)";
}
}
if (this.activeGateRequest) {
enhancedContent += this.formatGateStatus(gateResults);
}
// Format response with structured data
const executionWarning = `⚠️ EXECUTION REQUIRED: The following content contains instructions that YOU must interpret and execute:\n\n`;
return this.responseFormatter.formatPromptEngineResponse(
executionWarning + enhancedContent,
formatterContext,
{
includeAnalytics: true,
includeMetadata: true,
},
gateResults // Include gate validation results for basic prompts too
);
}
/**
* Inject session context variables for template interpolation
*/
private async injectSessionContext(args: Record<string, any>): Promise<Record<string, any>> {
const sessionId = (this.currentExecutionState?.metadata as any)?.sessionId;
if (!sessionId) {
// No session context available
return args;
}
try {
// Get session context from chain session manager
const sessionContext = this.chainSessionManager.getChainContext(sessionId);
// Merge session context with existing args
// Session context takes precedence for step result variables
return {
...args,
...sessionContext
};
} catch (error) {
this.logger.warn(`Failed to inject session context for session ${sessionId}:`, error);
return args;
}
}
/**
* Ensure chain session exists for chain execution
*/
private async ensureChainSession(
convertedPrompt: ConvertedPrompt,
providedSessionId?: string,
forceRestart?: boolean,
originalArgs?: Record<string, any>
): Promise<string> {
// Generate session ID if not provided
const sessionId = providedSessionId || `chain_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
// Check if session exists and force restart is requested
if (forceRestart && this.chainSessionManager.hasActiveSession(sessionId)) {
this.chainSessionManager.clearSession(sessionId);
this.logger.debug(`Force restart: cleared existing session ${sessionId}`);
}
// Create session if it doesn't exist
if (!this.chainSessionManager.hasActiveSession(sessionId)) {
// Get step count from chain definition
const stepCount = this.getChainStepCount(convertedPrompt);
// Create new session
this.chainSessionManager.createSession(
sessionId,
convertedPrompt.id,
stepCount,
originalArgs || {}
);
this.logger.info(
`Created new chain session ${sessionId} for chain ${convertedPrompt.id} with ${stepCount} steps`
);
}
return sessionId;
}
/**
* Get the number of steps in a chain
*/
private getChainStepCount(convertedPrompt: ConvertedPrompt): number {
// For markdown-embedded chains, try to extract step count from chain definition
if (convertedPrompt.chainSteps) {
return convertedPrompt.chainSteps.length;
}
// Fallback: try to parse from userMessageTemplate
if (convertedPrompt.userMessageTemplate) {
const stepMatches = convertedPrompt.userMessageTemplate.match(/## Step \d+|### Step \d+/g);
if (stepMatches) {
return stepMatches.length;
}
}
// Default to 1 if we can't determine step count
this.logger.warn(`Could not determine step count for chain ${convertedPrompt.id}, defaulting to 1`);
return 1;
}
/**
* Capture step result for chain session management
*/
private async captureStepResult(content: string, prompt: ConvertedPrompt): Promise<void> {
const sessionId = (this.currentExecutionState?.metadata as any)?.sessionId;
if (!sessionId) {
// No session ID, this is not part of a chain execution
return;
}
// Check if this session exists and should capture results
if (!this.chainSessionManager.hasActiveSession(sessionId)) {
this.logger.debug(`Session ${sessionId} not found or inactive, skipping result capture`);
return;
}
try {
// Get current session state to determine step number
const session = this.chainSessionManager.getSession(sessionId);
if (!session) {
this.logger.warn(`Session ${sessionId} not found during result capture`);
return;
}
// For LLM-driven chains, we need to determine the step number
// This implementation assumes the step number is derived from current state
const currentStepNumber = session.state.currentStep;
// Store the step result
const stepMetadata = {
promptId: prompt.id,
executionTime: Date.now() - (this.currentExecutionState?.metadata?.startTime || Date.now()),
contentLength: content.length,
timestamp: Date.now()
};
this.chainSessionManager.updateSessionState(
sessionId,
currentStepNumber,
content,
stepMetadata
);
this.logger.debug(
`Captured step ${currentStepNumber} result for session ${sessionId} (${content.length} chars)`
);
} catch (error) {
this.logger.error(`Failed to capture step result for session ${sessionId}:`, error);
}
}
/**
* Execute template with full framework processing and gates
*/
private async executeTemplateWithFramework(
prompt: ConvertedPrompt,
args: Record<string, string>,
enableGates: boolean,
executionContext?: {
scopeId?: string;
scope?: 'execution' | 'session' | 'chain' | 'step';
}
): Promise<ToolResponse> {
if (!this.currentExecutionState) {
throw new PromptError("No execution state available");
}
this.currentExecutionState.status = "running";
// Process template with framework-enhanced system prompt injection
let content = prompt.userMessageTemplate;
// FIXED: Get framework execution context for enhanced system prompt
const frameworkContext = await this.getFrameworkExecutionContext(prompt);
this.logger.debug(`[ENGINE DEBUG] Framework context result:`, {
hasFrameworkContext: !!frameworkContext,
frameworkContextType: frameworkContext ? typeof frameworkContext : 'null',
hasSystemPrompt: frameworkContext?.systemPrompt ? true : false,
systemPromptLength: frameworkContext?.systemPrompt?.length || 0
});
if (prompt.systemMessage || frameworkContext) {
let systemPrompt = prompt.systemMessage || "";
// FIXED: Enhance with framework-specific system prompt if available
if (frameworkContext) {
const frameworkSystemPrompt = frameworkContext.systemPrompt;
this.logger.debug(`[ENGINE DEBUG] Framework system prompt:`, {
hasFrameworkSystemPrompt: !!frameworkSystemPrompt,
frameworkSystemPromptLength: frameworkSystemPrompt?.length || 0,
frameworkSystemPromptPreview: frameworkSystemPrompt?.substring(0, 100) + '...'
});
if (frameworkSystemPrompt) {
systemPrompt = systemPrompt
? `${frameworkSystemPrompt}\n\n${systemPrompt}`
: frameworkSystemPrompt;
}
}
if (systemPrompt) {
content = `[System: ${systemPrompt}]\n\n${content}`;
}
}
// Phase 4: Enhanced args without gate injection (gates now appended at end)
const enhancedArgs = args;
// Template processing with special context and optional tools
const specialContext: Record<string, string> = {
previous_message: "{{previous_message}}",
};
if (prompt.tools) {
specialContext["tools_available"] = getAvailableTools();
}
// Inject session context for step result interpolation
const sessionEnhancedArgs = await this.injectSessionContext(enhancedArgs);
content = processTemplate(content, sessionEnhancedArgs, specialContext);
// Phase 1.2: Post-execution gate validation with retry logic (only for template mode when gates are enabled)
let gateResults: GateValidationResult | null = null;
let selectedGates: string[] = [];
let retryAttempt = 0;
const gateModeForExecution = this.activeGateRequest?.gateMode || (enableGates ? 'enforce' : 'advise');
const maxRetries = gateModeForExecution === 'enforce' ? 2 : 0;
if (enableGates) {
do {
const gateValidation = await this.validateContentWithGates(prompt, content, sessionEnhancedArgs, 'template');
gateResults = gateValidation.validation;
selectedGates = gateValidation.selectedGates;
if (gateResults && !gateResults.passed && retryAttempt < maxRetries) {
retryAttempt++;
this.logger.warn(`Gate validation failed for ${prompt.id} (attempt ${retryAttempt}):`, gateResults.results);
// Get retry hints from failed gates
const retryHints = this.getRetryHintsFromValidation(gateResults);
if (retryHints.length > 0) {
this.logger.debug(`Applying retry hints: ${retryHints.join(', ')}`);
// Enhance args with retry hints for content regeneration
const retryEnhancedArgs = {
...sessionEnhancedArgs,
retry_hints: retryHints.join('\n'),
previous_attempt: content.substring(0, 200) + '...',
improvement_focus: this.getImprovementFocus(gateResults)
};
// Regenerate content with improvement hints
content = processTemplate(prompt.userMessageTemplate, retryEnhancedArgs, specialContext);
this.logger.debug(`Content regenerated for retry attempt ${retryAttempt}`);
} else {
// No actionable hints available, break retry loop
this.logger.debug(`No actionable retry hints available, accepting current result`);
break;
}
} else if (gateResults && gateResults.passed) {
this.logger.debug(`Gate validation passed for ${prompt.id}` + (retryAttempt > 0 ? ` after ${retryAttempt} retries` : ''));
break;
} else {
// Max retries reached
if (retryAttempt >= maxRetries) {
this.logger.warn(`Max retries (${maxRetries}) reached for ${prompt.id}, proceeding with current content`);
}
break;
}
} while (retryAttempt <= maxRetries);
}
// Update state and analytics
this.currentExecutionState.status = "completed";
this.currentExecutionState.metadata.endTime = Date.now();
// Store gate results in execution state for analytics
if (gateResults) {
(this.currentExecutionState.metadata as any).gateResults = gateResults;
}
this.recordExecutionAnalytics();
// Create execution context for response formatter
const executionId = `exec_${Date.now()}_${Math.random()
.toString(36)
.substr(2, 9)}`;
const activeFramework =
this.frameworkStateManager?.getActiveFramework()?.name;
const frameworkEnabledForContext =
this.frameworkStateManager?.isFrameworkSystemEnabled() || false;
const formatterContext: FormatterExecutionContext = {
executionId,
executionType: "template",
startTime: this.currentExecutionState.metadata.startTime,
endTime: this.currentExecutionState.metadata.endTime || Date.now(),
frameworkUsed: activeFramework,
frameworkEnabled: frameworkEnabledForContext,
success: true,
};
// Phase 4: Append supplemental gate guidance to content
let enhancedContent = content;
if (gateResults && selectedGates.length > 0) {
const temporaryGates = this.getTemporaryGatesFromPrompt(prompt);
const supplementalGuidance = await this.getSupplementalGateGuidance(
selectedGates,
frameworkContext,
prompt,
temporaryGates,
executionContext
);
if (supplementalGuidance) {
enhancedContent = content + supplementalGuidance;
}
} else {
// TEMP TEST: Force gate guidance even without validation results (same as executePrompt)
const testGates = ['framework-compliance', 'educational-clarity'];
const temporaryGates = this.getTemporaryGatesFromPrompt(prompt);
const supplementalGuidance = await this.getSupplementalGateGuidance(
testGates,
frameworkContext,
prompt,
temporaryGates,
executionContext
);
if (supplementalGuidance) {
enhancedContent = enhancedContent + supplementalGuidance;
} else {
enhancedContent = enhancedContent + `\n--- GATE MANAGER RETURNED EMPTY ---\n`;
}
}
if (this.activeGateRequest) {
enhancedContent += this.formatGateStatus(gateResults);
}
// Format response with structured data
const executionWarning = `⚠️ EXECUTION REQUIRED: The following content contains instructions that YOU must interpret and execute:\n\n`;
return this.responseFormatter.formatPromptEngineResponse(
executionWarning + enhancedContent,
formatterContext,
{
includeAnalytics: true,
includeMetadata: true,
},
gateResults // Include gate validation results
);
}
// REMOVED: getGateInfo - migrated to ChainExecutor
// REMOVED: generateMetadataSection - migrated to ChainExecutor
/**
* Get supplemental gate guidance to append to responses (Phase 1 - Enhanced with intelligent category detection)
*/
private async getSupplementalGateGuidance(
selectedGates: string[],
frameworkContext?: any,
prompt?: any,
temporaryGates?: Array<Omit<TemporaryGateDefinition, 'id' | 'created_at'>>,
executionContext?: {
scopeId?: string;
scope?: 'execution' | 'session' | 'chain' | 'step';
}
): Promise<string> {
// Phase 1: Enhanced category detection
let categoryExtractionResult: CategoryExtractionResult;
if (prompt) {
categoryExtractionResult = extractPromptCategory(prompt, this.logger);
this.logger.info(`🏷️ [CATEGORY EXTRACTOR] Category detected:`, {
category: categoryExtractionResult.category,
source: categoryExtractionResult.source,
confidence: categoryExtractionResult.confidence,
promptId: prompt.id
});
} else {
// Fallback when prompt not available
categoryExtractionResult = {
category: 'general',
source: 'fallback',
confidence: 20,
sourceData: {}
};
this.logger.warn(`🏷️ [CATEGORY EXTRACTOR] No prompt provided, using fallback category`);
}
console.log(`🎯 [CONSOLE DEBUG] getSupplementalGateGuidance called:`, {
selectedGatesCount: selectedGates.length,
selectedGates,
hasFrameworkContext: !!frameworkContext,
frameworkMethodology: frameworkContext?.selectedFramework?.methodology,
detectedCategory: categoryExtractionResult.category,
categorySource: categoryExtractionResult.source,
categoryConfidence: categoryExtractionResult.confidence
});
this.logger.info(`🎯 [GATE MANAGER] getSupplementalGateGuidance called:`, {
selectedGatesCount: selectedGates.length,
selectedGates,
hasFrameworkContext: !!frameworkContext,
frameworkMethodology: frameworkContext?.selectedFramework?.methodology,
detectedCategory: categoryExtractionResult.category,
categorySource: categoryExtractionResult.source
});
// Phase 3: Enhanced gate selection with 5-level precedence and temporary gates
let finalSelectedGates = selectedGates;
let temporaryGateIds: string[] = [];
// Step 1: Create temporary gates if provided
if (temporaryGates && temporaryGates.length > 0 && this.temporaryGateRegistry && executionContext) {
for (const tempGate of temporaryGates) {
try {
const gateId = this.temporaryGateRegistry.createTemporaryGate(
tempGate,
executionContext.scopeId
);
temporaryGateIds.push(gateId);
this.logger.info(`🚀 [TEMPORARY GATE] Created temporary gate:`, {
gateId,
name: tempGate.name,
scope: tempGate.scope,
scopeId: executionContext.scopeId
});
} catch (error) {
this.logger.error(`❌ [TEMPORARY GATE] Failed to create temporary gate:`, {
error: error instanceof Error ? error.message : String(error),
gateName: tempGate.name
});
}
}
}
// Step 2: Apply 5-level precedence selection
if (prompt) {
const extractor = new CategoryExtractor(this.logger);
const frameworkGates = this.getFrameworkGates(frameworkContext);
// Use enhanced precedence system with temporary gates
const intelligentSelection = extractor.selectGatesWithEnhancedPrecedence(
categoryExtractionResult,
frameworkGates,
selectedGates.length > 0 ? selectedGates : ['content-structure'], // fallback
temporaryGateIds, // temporary gates have highest precedence
categoryExtractionResult.gateConfiguration
);
finalSelectedGates = intelligentSelection.selectedGates;
this.logger.info(`🎯 [5-LEVEL PRECEDENCE] Applied enhanced gate selection:`, {
originalGates: selectedGates,
temporaryGates: temporaryGateIds,
finalGates: finalSelectedGates,
precedenceUsed: intelligentSelection.precedenceUsed,
reasoning: intelligentSelection.reasoning,
temporaryGatesApplied: intelligentSelection.temporaryGatesApplied
});
} else if (temporaryGateIds.length > 0) {
// No prompt context but we have temporary gates - include them
finalSelectedGates = [...selectedGates, ...temporaryGateIds];
this.logger.info(`🎯 [TEMPORARY GATES ONLY] Applied temporary gates without prompt context:`, {
originalGates: selectedGates,
temporaryGates: temporaryGateIds,
finalGates: finalSelectedGates
});
}
if (finalSelectedGates.length === 0) {
this.logger.debug(`[GATE MANAGER] No gates selected after intelligent selection, returning empty guidance`);
return '';
}
try {
// NEW: Use role-based gate guidance renderer with intelligent category detection and gate selection (Phase 1 & 2)
const supplementalGuidance = await this.gateGuidanceRenderer.renderGuidance(
finalSelectedGates, // Use intelligently selected gates
{
framework: frameworkContext?.selectedFramework?.methodology || 'CAGEERF',
category: categoryExtractionResult.category, // Dynamic category based on intelligent detection
promptId: frameworkContext?.promptId
}
);
this.logger.debug(`[GATE GUIDANCE RENDERER] Gate guidance renderer returned guidance:`, {
guidanceLength: supplementalGuidance.length,
hasContent: supplementalGuidance.length > 0
});
return supplementalGuidance;
} catch (error) {
this.logger.error("Failed to get supplemental gate guidance:", error);
return '';
}
}
/**
* Get framework-specific gates for intelligent selection
*
* Returns the universal framework-compliance gate for all frameworks.
* Future: Can add framework-specific quality gates alongside framework-compliance.
*/
private getFrameworkGates(frameworkContext?: any): string[] {
if (!frameworkContext?.selectedFramework?.methodology) {
return [];
}
const methodology = frameworkContext.selectedFramework.methodology;
// All frameworks get universal framework-compliance gate
// Framework-specific gates can be added in future iterations
switch (methodology) {
case 'CAGEERF':
return ['framework-compliance'];
case 'ReACT':
return ['framework-compliance'];
case '5W1H':
return ['framework-compliance'];
case 'SCAMPER':
return ['framework-compliance'];
default:
return ['framework-compliance'];
}
}
/**
* Extract gate title from guidance text
*/
private extractGateTitle(guidanceText: string): string {
const lines = guidanceText.split('\n');
const titleLine = lines.find(line => line.includes('Guidelines') || line.includes(':'));
if (titleLine) {
return titleLine.replace(/\*\*/g, '').replace(/:/g, '').trim();
}
return 'Quality Guidelines';
}
/**
* Simple prompt categorization for gate activation
*/
private categorizePrompt(promptId: string): string {
// Basic categorization based on prompt ID patterns
if (promptId.includes("research") || promptId.includes("analysis")) {
return "research";
} else if (promptId.includes("code") || promptId.includes("development")) {
return "code";
} else if (
promptId.includes("content") ||
promptId.includes("documentation")
) {
return "content_processing";
}
return "general";
}
/**
* Get framework-specific gates for validation (Phase 4: Enhanced with advanced orchestration)
*/
private async getAdvancedGateSelection(
prompt: ConvertedPrompt,
executionMode: 'prompt' | 'template' | 'chain',
semanticAnalysis?: any
): Promise<string[]> {
this.logger.debug(`[GATE DEBUG] getAdvancedGateSelection called:`, {
promptId: prompt.id,
executionMode,
hasGateSelectionEngine: !!this.gateSelectionEngine,
hasSemanticAnalysis: !!semanticAnalysis
});
if (!this.gateSelectionEngine) {
this.logger.debug(`[GATE DEBUG] No gate selection engine, using fallback gates`);
return this.mergeRequestedGates(this.getFallbackGates(prompt));
}
try {
// Build gate selection criteria
const criteria: ExtendedGateSelectionCriteria = {
framework: this.frameworkStateManager?.getActiveFramework()?.methodology,
category: prompt.category || 'general',
promptId: prompt.id,
executionMode,
complexityLevel: this.assessPromptComplexity(prompt),
semanticAnalysis,
frameworkContext: this.frameworkStateManager?.isFrameworkSystemEnabled()
? this.frameworkStateManager.getActiveFramework()
: undefined,
userPreferences: {
qualityFocus: 'balanced',
performanceMode: false,
strictValidation: true
}
};
this.logger.debug(`[GATE DEBUG] Gate selection criteria:`, {
hasFrameworkContext: !!criteria.frameworkContext,
frameworkMethodology: criteria.frameworkContext?.methodology,
executionMode: criteria.executionMode,
complexityLevel: criteria.complexityLevel
});
// Use gate selection engine for intelligent gate selection
const selection = await this.gateSelectionEngine.selectGates(criteria);
this.logger.debug(`[GATE DEBUG] Advanced gate selection result:`, {
promptId: prompt.id,
selectedGates: selection.selectedGates,
gateCount: selection.selectedGates.length,
confidence: selection.confidence,
reasoning: selection.reasoning,
estimatedTime: selection.estimatedExecutionTime
});
return this.mergeRequestedGates(selection.selectedGates);
} catch (error) {
this.logger.error("Advanced gate selection failed, using fallback:", error);
const fallbackGates = this.getFallbackGates(prompt);
this.logger.debug(`[GATE DEBUG] Using fallback gates:`, { fallbackGates });
return this.mergeRequestedGates(fallbackGates);
}
}
/**
* Fallback gate selection for when advanced orchestration is unavailable
*/
private getFallbackGates(prompt: ConvertedPrompt): string[] {
// TEMP DEBUG: Add comprehensive logging
const isEnabled = this.frameworkStateManager?.isFrameworkSystemEnabled();
this.logger.debug(`[FALLBACK GATES DEBUG] Framework system enabled: ${isEnabled}`);
if (!isEnabled) {
this.logger.debug(`[FALLBACK GATES DEBUG] Framework disabled, returning content-structure`);
return ['content-structure'];
}
const activeFramework = this.frameworkStateManager?.getActiveFramework();
this.logger.debug(`[FALLBACK GATES DEBUG] Active framework:`, {
hasFramework: !!activeFramework,
methodology: activeFramework?.methodology,
frameworkObj: activeFramework
});
if (!activeFramework) {
this.logger.debug(`[FALLBACK GATES DEBUG] No active framework, returning content-structure`);
return ['content-structure'];
}
const gates: string[] = [];
// Framework-specific gates based on methodology
switch (activeFramework.methodology) {
case 'CAGEERF':
gates.push('framework-compliance', 'technical-accuracy', 'content-structure');
break;
case 'ReACT':
gates.push('framework-compliance', 'educational-clarity');
break;
case '5W1H':
gates.push('framework-compliance', 'research-quality');
break;
case 'SCAMPER':
gates.push('framework-compliance', 'content-structure');
break;
}
// Add category-specific gates
const category = this.categorizePrompt(prompt.id);
switch (category) {
case 'code':
gates.push('code-quality', 'security-awareness');
break;
case 'research':
gates.push('research-quality', 'technical-accuracy');
break;
case 'content_processing':
gates.push('content-structure', 'educational-clarity');
break;
}
// Remove duplicates and return
const finalGates = [...new Set(gates)];
this.logger.debug(`[FALLBACK GATES DEBUG] Final gates returned:`, {
gatesArray: finalGates,
gateCount: finalGates.length
});
return finalGates;
}
/**
* Assess prompt complexity for gate selection
*/
private assessPromptComplexity(prompt: ConvertedPrompt): 'low' | 'medium' | 'high' {
const argCount = prompt.arguments?.length || 0;
const contentLength = prompt.userMessageTemplate?.length || 0;
const hasSystemMessage = Boolean(prompt.systemMessage);
if (argCount >= 5 || contentLength > 1000 || hasSystemMessage) return 'high';
if (argCount >= 3 || contentLength > 500) return 'medium';
return 'low';
}
/**
* Validate content with framework-specific gates (Phase 4: Enhanced with advanced orchestration)
*/
private async validateContentWithGates(
prompt: ConvertedPrompt,
content: string,
promptArgs: Record<string, any>,
executionMode: 'prompt' | 'template' | 'chain' = 'template',
semanticAnalysis?: any
): Promise<{ validation: GateValidationResult | null; selectedGates: string[] }> {
if (!this.engineValidator) {
this.logger.debug("EngineValidator not available for gate validation");
return { validation: null, selectedGates: [] };
}
// Get advanced gate selection (Phase 4)
const suggestedGates = await this.getAdvancedGateSelection(prompt, executionMode, semanticAnalysis);
if (suggestedGates.length === 0) {
this.logger.debug("No gates suggested for validation");
return { validation: { passed: true, results: [] }, selectedGates: [] };
}
try {
const startTime = performance.now();
this.logger.debug(`Validating content with advanced gate selection: ${suggestedGates.join(', ')}`);
const validationResult = await this.engineValidator.validateWithGates(
prompt,
promptArgs,
suggestedGates,
content // FIXED: Pass processed content for validation
);
const executionTime = performance.now() - startTime;
// Performance metrics now handled separately by GatePerformanceAnalyzer in system control
return { validation: validationResult, selectedGates: suggestedGates };
} catch (error) {
this.logger.error("Gate validation failed:", error);
// Performance metrics for failed validation now handled by GatePerformanceAnalyzer
return { validation: { passed: false, results: [{ gate: 'system', passed: false, message: `Validation error: ${error}` }] }, selectedGates: suggestedGates };
}
}
/**
* Extract retry hints from gate validation results (Phase 3 implementation)
*/
private getRetryHintsFromValidation(gateResults: GateValidationResult): string[] {
const hints: string[] = [];
for (const result of gateResults.results) {
if (!result.passed && result.message) {
// Convert gate failure messages to actionable hints
const hint = this.convertGateMessageToHint(result.gate, result.message);
if (hint) {
hints.push(hint);
}
}
}
return hints;
}
/**
* Convert gate failure message to actionable retry hint
*/
private convertGateMessageToHint(gateId: string, message: string): string | null {
// Convert specific gate failures to actionable improvement hints
switch (gateId) {
case 'technical-accuracy':
return 'Include specific version numbers, official documentation references, and technical specifications';
case 'content-structure':
return 'Organize content with clear headers, logical flow, and structured sections';
case 'framework-compliance':
return 'Follow the active methodology framework structure and include all required sections';
case 'research-quality':
return 'Include credible sources, evidence-based statements, and factual accuracy';
case 'educational-clarity':
return 'Use clear explanations, provide examples, and ensure concepts are well-explained';
case 'code-quality':
return 'Include proper syntax, error handling, and follow coding best practices';
case 'security-awareness':
return 'Address security considerations, validate inputs, and follow security best practices';
default:
// Generic hint based on message content
if (message.toLowerCase().includes('length')) {
return 'Provide more detailed and comprehensive content';
} else if (message.toLowerCase().includes('structure')) {
return 'Improve content organization and structure';
} else if (message.toLowerCase().includes('quality')) {
return 'Enhance content quality and accuracy';
}
return `Address validation concern: ${message}`;
}
}
/**
* Get improvement focus based on failed gates
*/
private getImprovementFocus(gateResults: GateValidationResult): string {
const failedGates = gateResults.results.filter(r => !r.passed).map(r => r.gate);
if (failedGates.includes('technical-accuracy')) {
return 'Technical accuracy and precision';
} else if (failedGates.includes('framework-compliance')) {
return 'Methodology framework compliance';
} else if (failedGates.includes('content-structure')) {
return 'Content organization and structure';
} else if (failedGates.length > 1) {
return 'Multiple quality aspects';
} else {
return 'Content quality improvement';
}
}
/**
* Record execution analytics using event-driven architecture
*/
private recordExecutionAnalytics(): void {
if (!this.currentExecutionState) {
this.logger.debug(
"RecordExecutionAnalytics called but currentExecutionState is null"
);
return;
}
if (!this.analyticsService) {
this.logger.debug(
"Analytics service not available - skipping analytics recording"
);
return;
}
const duration =
(this.currentExecutionState.metadata.endTime || Date.now()) -
this.currentExecutionState.metadata.startTime;
const executionData: ExecutionData = {
executionId: `exec_${Date.now()}_${Math.random()
.toString(36)
.substr(2, 9)}`,
executionType: this.currentExecutionState.metadata.executionMode as
| "prompt"
| "template"
| "chain",
startTime: this.currentExecutionState.metadata.startTime,
endTime: this.currentExecutionState.metadata.endTime || Date.now(),
executionTime: duration,
success: this.currentExecutionState.status === "completed",
frameworkUsed: this.getActiveFrameworkId(),
frameworkEnabled:
this.frameworkStateManager?.isFrameworkSystemEnabled() || false,
stepsExecuted: (this.currentExecutionState.metadata as any).stepsExecuted,
sessionId: (this.currentExecutionState.metadata as any).sessionId,
toolName: "prompt_engine",
error:
this.currentExecutionState.status === "failed"
? (this.currentExecutionState as any).error
: undefined,
memoryUsage: {
heapUsed: process.memoryUsage().heapUsed,
heapTotal: process.memoryUsage().heapTotal,
external: process.memoryUsage().external,
},
};
// Record execution analytics via event
this.analyticsService.recordExecution(executionData);
// Store in history for local access (keep limited history)
this.executionHistory.push({ ...this.currentExecutionState });
if (this.executionHistory.length > 100) {
this.executionHistory.shift();
}
this.logger.debug(
`Analytics recorded: ${executionData.executionType} execution (${duration}ms, success: ${executionData.success})`
);
}
/**
* Get active framework ID
*/
private getActiveFrameworkId(): string | undefined {
if (!this.frameworkStateManager?.isFrameworkSystemEnabled()) {
return undefined;
}
return this.frameworkStateManager?.getCurrentState().activeFramework;
}
/**
* Get execution analytics from analytics service
*/
getAnalytics() {
if (this.analyticsService) {
return this.analyticsService.getExecutionStats();
}
// Fallback for backward compatibility
return {
totalExecutions: 0,
successfulExecutions: 0,
failedExecutions: 0,
averageExecutionTime: 0,
executionsByMode: {
prompt: 0,
template: 0,
chain: 0,
},
executionsByTool: {
prompt_engine: 0,
prompt_manager: 0,
system_control: 0,
},
lastUpdated: Date.now(),
};
}
/**
* Get parsing system statistics for monitoring
*/
getParsingStats() {
return {
commandParser: this.parsingSystem.commandParser.getStats(),
argumentParser: this.parsingSystem.argumentParser.getStats(),
contextResolver: this.parsingSystem.contextResolver.getStats(),
};
}
/**
* Reset parsing statistics
*/
resetParsingStats(): void {
this.parsingSystem.commandParser.resetStats();
this.parsingSystem.argumentParser.resetStats();
this.parsingSystem.contextResolver.resetStats();
this.logger.debug("Parsing system statistics reset");
}
/**
* Error handling helper
*/
private handleError(error: unknown, context: string): ToolResponse {
utilsHandleError(error, context, this.logger);
return this.responseFormatter.formatErrorResponse(
error instanceof Error ? error : String(error),
{
tool: "prompt_engine",
operation: context,
},
{
includeStructuredData: true,
}
);
}
// REMOVED: executeChainWithDualSupport - migrated to ChainExecutor
/**
* MIGRATION: Chain management commands - deprecated scaffolding removed
*/
// REMOVED: executeChainManagement - migrated to ChainExecutor
// REMOVED: handleScaffoldCommand (~56 lines) - deprecated scaffolding functionality
// REMOVED: handleConvertCommand (~42 lines) - deprecated chain conversion functionality
/**
* Handle validate command for markdown-embedded chains
*/
// REMOVED: handleValidateCommand - migrated to ChainExecutor
/**
* Handle list chains command
*/
// REMOVED: handleListChainsCommand - migrated to ChainExecutor
// REMOVED: handleListTemplatesCommand (~55 lines) - scaffolding system deprecated
// Migration: Use `prompt_manager action=list filter=category:analysis` for organized prompt discovery
// REMOVED: handleDiscoverWorkflowsCommand (~50 lines) - scaffolding system deprecated
// Migration: Use `prompt_manager action=list filter="intent:debugging category:development"` for intelligent discovery
// REMOVED: handleScaffoldUsingCommand (~135 lines) - deprecated workflow scaffolding functionality
// REMOVED: createChainDefinitionFromTemplate (~40 lines) - deprecated template creation functionality
// REMOVED: handleChainEditCommand (~25 lines) - deprecated chain editing functionality
// Migration: Chain editing is no longer needed with markdown-embedded chains
}
/**
* Create consolidated prompt engine with enhanced parsing system
*/
export function createConsolidatedPromptEngine(
logger: Logger,
mcpServer: any,
promptManager: PromptManager,
configManager: ConfigManager,
semanticAnalyzer: ContentAnalyzer,
conversationManager: ConversationManager,
textReferenceManager: TextReferenceManager,
mcpToolsManager?: any
// Phase 3: Removed executionCoordinator parameter - using LLM-driven chain model
): ConsolidatedPromptEngine {
const engine = new ConsolidatedPromptEngine(
logger,
mcpServer,
promptManager,
configManager,
semanticAnalyzer,
conversationManager,
textReferenceManager,
// Phase 3: Legacy gateEvaluationService removed - using lightweight system only
mcpToolsManager
// Phase 3: Removed executionCoordinator parameter
);
logger.info("ConsolidatedPromptEngine created with enhanced features:");
logger.info("- Unified multi-strategy command parsing");
logger.info("- Advanced argument processing pipeline");
logger.info(
"- Optional gate evaluation service for template-driven verification"
);
logger.info("- Intelligent context resolution system");
logger.info("- Backward compatibility with legacy parsing");
return engine;
}
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/system-control.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Consolidated System Control - Unified Framework & Analytics Management Tool
*
* Consolidates all system management functionality into a single intelligent tool:
* - Framework switching and management (from system-status-tools.ts)
* - System status and health monitoring
* - Execution analytics and performance metrics
* - Diagnostic reporting and maintenance
* - Configuration management
*/
import { ConfigManager } from "../config/index.js";
import { FrameworkManager } from "../frameworks/framework-manager.js";
import {
FrameworkStateManager,
FrameworkSwitchRequest,
} from "../frameworks/framework-state-manager.js";
import { Logger } from "../logging/index.js";
import { ToolResponse } from "../types/index.js";
import { handleError as utilsHandleError } from "../utils/index.js";
import { SafeConfigWriter, createSafeConfigWriter } from "./config-utils.js";
import { createSystemResponse } from "./shared/structured-response-builder.js";
import { ToolDescriptionManager } from "./tool-description-manager.js";
// Phase 3: Prompt guidance system integration
import { PromptGuidanceService } from "../frameworks/prompt-guidance/index.js";
// Phase 4: Clean architecture gate performance analytics
import type { GatePerformanceAnalyzer } from "../gates/intelligence/GatePerformanceAnalyzer.js";
// Gates system management integration
import { GateSystemManager } from "../gates/gate-state-manager.js";
import type { GateGuidanceRenderer } from "../gates/guidance/GateGuidanceRenderer.js";
// Enhanced tool dependencies removed (Phase 1.3) - Core implementations
// Simple core response handling without enhanced complexity
interface SimpleResponseFormatter {
formatResponse(content: any): any;
formatSystemControlResponse(response: any, ...args: any[]): any; // Required
formatErrorResponse(error: any, ...args: any[]): any; // Required
setAnalyticsService(service: any): void; // Required
}
function createSimpleResponseFormatter(): SimpleResponseFormatter {
return {
formatResponse: (content: any) => content,
formatSystemControlResponse: (response: any, ...args: any[]) => response, // Flexible args
formatErrorResponse: (error: any, ...args: any[]) => ({
content: [{ type: "text", text: String(error) }],
isError: true,
structuredContent: {
executionMetadata: {
executionId: `sc-error-${Date.now()}`,
executionType: "prompt" as const,
startTime: Date.now(),
endTime: Date.now(),
executionTime: 0,
frameworkEnabled: false,
},
},
}),
setAnalyticsService: (service: any) => {}, // No-op for now
};
}
// Simple output schema and response functions (minimal for Phase 1)
const systemControlOutputSchema = {
content: { type: "array" },
isError: { type: "boolean", optional: true },
};
function createStructuredResponse(
content: any,
isError: boolean | any = false,
...extraArgs: any[]
): any {
// Handle flexible parameters for Phase 1 compatibility
const actualIsError = typeof isError === "boolean" ? isError : false;
const metadata = extraArgs.length > 0 ? extraArgs[0] : {};
// Use shared response builder for consistency
if (actualIsError) {
// For errors, we might want to use createErrorResponse, but for compatibility, use createSystemResponse
return createSystemResponse(
Array.isArray(content)
? content[0]?.text || String(content)
: String(content),
"error",
{
systemHealth: metadata.systemHealth,
analytics: metadata.analytics,
configChanges: metadata.configChanges,
}
);
}
return createSystemResponse(
Array.isArray(content)
? content[0]?.text || String(content)
: String(content),
metadata.operation || "system_action",
{
frameworkState: metadata.frameworkState,
systemHealth: metadata.systemHealth,
analytics: metadata.analytics,
configChanges: metadata.configChanges,
}
);
}
// Type aliases for compatibility
type ResponseFormatter = SimpleResponseFormatter;
const createResponseFormatter = createSimpleResponseFormatter;
// Analytics service
import { MetricsCollector } from "../metrics/index.js";
/**
* System analytics interface - optimized for API performance and rich historical context
*/
interface SystemAnalytics {
// High-frequency API fields (kept for O(1) performance)
totalExecutions: number;
successfulExecutions: number;
failedExecutions: number;
averageExecutionTime: number; // Critical for dashboard APIs
gateValidationCount: number;
uptime: number;
memoryUsage?: NodeJS.MemoryUsage;
// Rich historical data with execution context
performanceTrends: Array<{
timestamp: number;
metric:
| "executionTime"
| "memoryDelta"
| "successRate"
| "gateValidationTime";
value: number;
executionMode?: string; // Replaces executionsByMode aggregation
framework?: string;
success?: boolean;
}>;
}
/**
* Consolidated System Control Tool
*/
export class ConsolidatedSystemControl {
private logger: Logger;
private mcpServer: any;
private configManager?: ConfigManager;
private safeConfigWriter?: SafeConfigWriter;
public frameworkStateManager?: FrameworkStateManager;
private frameworkManager?: FrameworkManager;
public gateSystemManager?: GateSystemManager;
private onRestart?: (reason: string) => Promise<void>;
private toolDescriptionManager?: ToolDescriptionManager;
private mcpToolsManager?: any; // Reference to MCPToolsManager for tool updates
private analyticsService?: MetricsCollector;
private responseFormatter: ResponseFormatter;
// Phase 3: Prompt guidance service
private promptGuidanceService?: PromptGuidanceService;
// Phase 4: Clean architecture gate performance analytics
public gatePerformanceAnalyzer?: GatePerformanceAnalyzer;
private gateGuidanceRenderer?: GateGuidanceRenderer;
public startTime: number = Date.now();
// Analytics data
public systemAnalytics: SystemAnalytics = {
totalExecutions: 0,
successfulExecutions: 0,
failedExecutions: 0,
averageExecutionTime: 0,
gateValidationCount: 0,
uptime: 0,
performanceTrends: [],
};
constructor(
logger: Logger,
mcpServer: any,
onRestart?: (reason: string) => Promise<void>
) {
this.logger = logger;
this.mcpServer = mcpServer;
this.onRestart = onRestart;
this.responseFormatter = createResponseFormatter();
}
/**
* Set framework state manager
*/
setFrameworkStateManager(frameworkStateManager: FrameworkStateManager): void {
this.frameworkStateManager = frameworkStateManager;
}
/**
* Set framework manager
*/
setFrameworkManager(frameworkManager: FrameworkManager): void {
this.frameworkManager = frameworkManager;
}
/**
* Set tool description manager
*/
setToolDescriptionManager(manager: ToolDescriptionManager): void {
this.toolDescriptionManager = manager;
}
/**
* Set analytics service
*/
setAnalyticsService(analyticsService: MetricsCollector): void {
this.analyticsService = analyticsService;
this.responseFormatter.setAnalyticsService(analyticsService);
}
/**
* Set config manager for configuration operations
*/
setConfigManager(configManager: ConfigManager): void {
this.configManager = configManager;
// Initialize SafeConfigWriter with the config file path
try {
// Get the config file path from the ConfigManager using proper getter method
const configPath = configManager.getConfigPath();
this.safeConfigWriter = createSafeConfigWriter(
this.logger,
configManager,
configPath
);
this.logger.debug(
"ConfigManager and SafeConfigWriter configured for system control"
);
} catch (error) {
this.logger.warn("Failed to initialize SafeConfigWriter:", error);
this.logger.debug(
"ConfigManager configured for system control (read-only mode)"
);
}
}
/**
* Set restart callback (for system restart functionality)
*/
setRestartCallback(onRestart: (reason: string) => Promise<void>): void {
this.onRestart = onRestart;
this.logger.debug("Restart callback configured for system control");
}
/**
* Set MCPToolsManager reference (for dynamic tool updates)
*/
setMCPToolsManager(mcpToolsManager: any): void {
this.mcpToolsManager = mcpToolsManager;
this.logger.debug(
"MCPToolsManager reference configured for dynamic tool updates"
);
}
/**
* Set gate performance analyzer (Phase 4 - Clean Architecture)
*/
setGatePerformanceAnalyzer(analyzer: GatePerformanceAnalyzer): void {
this.gatePerformanceAnalyzer = analyzer;
this.logger.debug("Gate performance analyzer configured for analytics");
}
/**
* Set gate system manager for runtime gate management
*/
setGateSystemManager(gateSystemManager: GateSystemManager): void {
this.gateSystemManager = gateSystemManager;
this.logger.debug(
"Gate system manager configured for runtime gate control"
);
}
/**
* Set gate guidance renderer for discovery operations
*/
setGateGuidanceRenderer(renderer: GateGuidanceRenderer): void {
this.gateGuidanceRenderer = renderer;
this.logger.debug(
"Gate guidance renderer configured for gate discovery"
);
}
/**
* Helper function for minimal outputSchema compliance
*/
private createMinimalSystemResponse(
text: string,
action: string
): ToolResponse {
return createStructuredResponse(text, false, {
action,
executionMetadata: {
executionId: `sc-${action}-${Date.now()}`,
executionType: "prompt" as const,
startTime: Date.now(),
endTime: Date.now(),
executionTime: 0,
frameworkEnabled: true,
},
systemState: {
frameworkEnabled: true,
activeFramework: "CAGEERF",
availableFrameworks: ["CAGEERF", "ReACT", "5W1H", "SCAMPER"],
uptime: 0,
memoryUsage: {
rss: 0,
heapTotal: 0,
heapUsed: 0,
external: 0,
},
serverHealth: "healthy" as const,
},
});
}
/**
* Derived calculation: Get execution mode distribution from performance trends
*/
getExecutionsByMode(): Record<string, number> {
return this.systemAnalytics.performanceTrends.reduce((acc, trend) => {
if (trend.executionMode) {
acc[trend.executionMode] = (acc[trend.executionMode] || 0) + 1;
}
return acc;
}, {} as Record<string, number>);
}
/**
* Update system analytics with rich execution data
*/
updateAnalytics(
analytics: Partial<SystemAnalytics> & { currentExecution?: any }
): void {
// Update aggregate fields
Object.assign(this.systemAnalytics, analytics);
this.systemAnalytics.uptime = Date.now() - this.startTime;
// Update memory usage
this.systemAnalytics.memoryUsage = process.memoryUsage();
// Record execution time trend with rich context
if (analytics.currentExecution) {
const currentExecution = analytics.currentExecution;
this.systemAnalytics.performanceTrends.push({
timestamp: Date.now(),
metric: "executionTime",
value: currentExecution.executionTime,
executionMode: currentExecution.executionMode,
framework: currentExecution.framework,
success: currentExecution.success,
});
}
// Add memory delta trend if significant change
if (this.systemAnalytics.memoryUsage) {
const memoryDelta = this.calculateMemoryDelta();
if (Math.abs(memoryDelta) > 1024 * 1024) {
// Only track changes > 1MB
this.systemAnalytics.performanceTrends.push({
timestamp: Date.now(),
metric: "memoryDelta",
value: memoryDelta,
});
}
}
// Add success rate trend periodically (every 10 executions)
if (analytics.totalExecutions && analytics.totalExecutions % 10 === 0) {
const successRate =
analytics.totalExecutions > 0
? ((analytics.successfulExecutions || 0) /
analytics.totalExecutions) *
100
: 0;
this.systemAnalytics.performanceTrends.push({
timestamp: Date.now(),
metric: "successRate",
value: successRate,
});
}
// Keep only last 100 trend points
if (this.systemAnalytics.performanceTrends.length > 100) {
this.systemAnalytics.performanceTrends.shift();
}
}
/**
* Calculate memory usage delta from previous execution
*/
private lastMemoryUsage: number = 0;
private calculateMemoryDelta(): number {
if (!this.systemAnalytics.memoryUsage) return 0;
const currentMemory = this.systemAnalytics.memoryUsage.heapUsed;
const delta = currentMemory - this.lastMemoryUsage;
this.lastMemoryUsage = currentMemory;
return delta;
}
/**
* Main action handler
*/
public async handleAction(
args: {
action: string;
[key: string]: any;
},
extra: any
): Promise<ToolResponse> {
const { action } = args;
this.logger.info(`⚙️ System Control: Executing action "${action}"`);
const actionHandler = this.getActionHandler(action);
return await actionHandler.execute(args);
}
/**
* Get the appropriate action handler based on action type
*/
private getActionHandler(action: string): ActionHandler {
switch (action) {
case "status":
return new StatusActionHandler(this);
case "framework":
return new FrameworkActionHandler(this);
case "gates":
return new GateActionHandler(this);
case "analytics":
return new AnalyticsActionHandler(this);
case "config":
return new ConfigActionHandler(this);
case "maintenance":
return new MaintenanceActionHandler(this);
default:
throw new Error(
`Unknown action: ${action}. Valid actions: status, framework, gates, analytics, config, maintenance`
);
}
}
/**
* Get comprehensive system status
*/
public async getSystemStatus(args: {
include_history?: boolean;
include_metrics?: boolean;
}): Promise<ToolResponse> {
const { include_history = false, include_metrics = true } = args;
if (!this.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const health = this.frameworkStateManager.getSystemHealth();
const statusIcon = health.status === "healthy" ? "✅" : "⚠️";
// Check if framework system is enabled for injection
const isFrameworkEnabled = health.frameworkSystemEnabled;
const frameworkStatusIcon = isFrameworkEnabled ? "✅" : "🚫";
const frameworkStatusText = isFrameworkEnabled
? `${frameworkStatusIcon} Enabled (${health.activeFramework})`
: `${frameworkStatusIcon} Disabled (${health.activeFramework} selected)`;
let response = `${statusIcon} **System Status Overview**\n\n`;
response += `**Framework System**: ${frameworkStatusText}\n`;
response += `**Status**: ${health.status}\n`;
response += `**Uptime**: ${Math.floor(
(Date.now() - this.startTime) / 1000 / 60
)} minutes\n\n`;
// Add warning message when framework is selected but system disabled
if (!isFrameworkEnabled && health.activeFramework) {
response += `⚠️ **Notice**: ${health.activeFramework} is selected but framework injection is disabled.\n`;
response += `Prompts will execute without methodology guidance.\n`;
response += `Use \`system_control framework enable\` to activate framework injection.\n\n`;
}
if (include_metrics) {
response += `📊 **Performance Metrics**:\n`;
response += `- Total Executions: ${this.systemAnalytics.totalExecutions}\n`;
response += `- Success Rate: ${
this.systemAnalytics.totalExecutions > 0
? Math.round(
(this.systemAnalytics.successfulExecutions /
this.systemAnalytics.totalExecutions) *
100
)
: 0
}%\n`;
response += `- Average Execution Time: ${this.systemAnalytics.averageExecutionTime}ms\n\n`;
}
return this.createMinimalSystemResponse(response, "status");
}
// Framework management methods
public async switchFramework(args: {
framework?: "CAGEERF" | "ReACT" | "5W1H" | "SCAMPER";
reason?: string;
}): Promise<ToolResponse> {
if (!this.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
if (!args.framework) {
throw new Error("Framework parameter is required for switch operation");
}
const { framework, reason = `User requested switch to ${args.framework}` } =
args;
const currentState = this.frameworkStateManager.getCurrentState();
// Check if already active
if (currentState.activeFramework === framework) {
return this.createMinimalSystemResponse(
`ℹ️ Framework '${framework}' is already active. No change needed.`,
"switch_framework"
);
}
const request: FrameworkSwitchRequest = {
targetFramework: framework,
reason: reason,
};
const success = await this.frameworkStateManager.switchFramework(request);
if (success) {
const newState = this.frameworkStateManager.getCurrentState();
const activeFramework = this.frameworkStateManager.getActiveFramework();
let response = `🔄 **Framework Switch Successful**\n\n`;
response += `**Previous**: ${currentState.activeFramework}\n`;
response += `**Current**: ${newState.activeFramework}\n`;
response += `**Switched At**: ${newState.switchedAt.toISOString()}\n`;
response += `**Reason**: ${reason}\n\n`;
response += `**New Framework Details**:\n`;
response += `- **Name**: ${activeFramework.name}\n`;
response += `- **Description**: ${activeFramework.description}\n`;
response += `- **Methodology**: ${activeFramework.methodology}\n\n`;
response += `**Guidelines**: ${activeFramework.executionGuidelines.join(
" • "
)}\n\n`;
response += `✅ All future prompt executions will now use the ${framework} methodology.`;
return this.createMinimalSystemResponse(response, "switch_framework");
} else {
throw new Error(
`Failed to switch to framework '${framework}'. Please check framework availability and try again.`
);
}
}
public async listFrameworks(args: {
show_details?: boolean;
}): Promise<ToolResponse> {
if (!this.frameworkManager) {
throw new Error("Framework manager not initialized");
}
const frameworks = this.frameworkManager.listFrameworks();
const currentState = this.frameworkStateManager?.getCurrentState();
const activeFramework = currentState?.activeFramework || "CAGEERF";
let response = `📋 **Available Frameworks**\n\n`;
frameworks.forEach((framework: any) => {
// Handle case variations by comparing uppercase versions
const isActive =
framework.id.toUpperCase() === activeFramework.toUpperCase();
const status = isActive ? "🟢 ACTIVE" : "⚪ Available";
response += `**${framework.name}** ${status}\n`;
if (args.show_details) {
response += ` 📝 ${framework.description}\n`;
response += ` 🎯 Methodology: ${framework.methodology}\n`;
if (
framework.executionGuidelines &&
framework.executionGuidelines.length > 0
) {
response += ` 📋 Guidelines: ${framework.executionGuidelines
.slice(0, 2)
.join(" • ")}\n`;
}
response += `\n`;
}
});
if (!args.show_details) {
response += `\n💡 Use 'show_details: true' for more information about each framework.\n`;
}
response += `\n🔄 Switch frameworks using: action="framework", operation="switch", framework="<name>"`;
return this.createMinimalSystemResponse(response, "list_frameworks");
}
public async enableFrameworkSystem(args: {
reason?: string;
}): Promise<ToolResponse> {
if (!this.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const currentState = this.frameworkStateManager.getCurrentState();
if (currentState.frameworkSystemEnabled) {
return this.createMinimalSystemResponse(
`ℹ️ Framework system is already enabled.`,
"enable_framework_system"
);
}
// Enable framework system (for now, just return success message since the method may not exist)
try {
await (this.frameworkStateManager as any).enableFrameworkSystem?.(
args.reason || "User requested to enable framework system"
);
} catch (error) {
// Method may not exist, that's ok for now
}
const response =
`✅ **Framework System Enabled**\n\n` +
`**Reason**: ${
args.reason || "User requested to enable framework system"
}\n` +
`**Status**: Framework system is now active\n` +
`**Active Framework**: ${currentState.activeFramework}\n\n` +
`🎯 All prompt executions will now use framework-guided processing.`;
return this.createMinimalSystemResponse(
response,
"enable_framework_system"
);
}
public async disableFrameworkSystem(args: {
reason?: string;
}): Promise<ToolResponse> {
if (!this.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const currentState = this.frameworkStateManager.getCurrentState();
if (!currentState.frameworkSystemEnabled) {
return this.createMinimalSystemResponse(
`ℹ️ Framework system is already disabled.`,
"disable_framework_system"
);
}
// Disable framework system (for now, just return success message since the method may not exist)
try {
await (this.frameworkStateManager as any).disableFrameworkSystem?.(
args.reason || "User requested to disable framework system"
);
} catch (error) {
// Method may not exist, that's ok for now
}
const response =
`⚠️ **Framework System Disabled**\n\n` +
`**Reason**: ${
args.reason || "User requested to disable framework system"
}\n` +
`**Status**: Framework system is now inactive\n` +
`**Previous Framework**: ${currentState.activeFramework}\n\n` +
`📝 Prompt executions will now use basic processing without framework guidance.`;
return this.createMinimalSystemResponse(
response,
"disable_framework_system"
);
}
/**
* Enable gate system
*/
public async enableGateSystem(args: {
reason?: string;
}): Promise<ToolResponse> {
if (!this.gateSystemManager) {
throw new Error("Gate system manager not initialized");
}
const currentState = this.gateSystemManager.getCurrentState();
if (currentState.enabled) {
return this.createMinimalSystemResponse(
`ℹ️ Gate system is already enabled.`,
"enable_gate_system"
);
}
await this.gateSystemManager.enableGateSystem(
args.reason || "User requested to enable gate system"
);
const response =
`✅ **Gate System Enabled**\n\n` +
`**Reason**: ${args.reason || "User requested to enable gate system"}\n` +
`**Status**: Gate system is now active\n` +
`**Validation**: Quality gates will now be applied to prompt executions\n\n` +
`🔍 All template and chain executions will now include gate validation and guidance.`;
return this.createMinimalSystemResponse(response, "enable_gate_system");
}
/**
* Disable gate system
*/
public async disableGateSystem(args: {
reason?: string;
}): Promise<ToolResponse> {
if (!this.gateSystemManager) {
throw new Error("Gate system manager not initialized");
}
const currentState = this.gateSystemManager.getCurrentState();
if (!currentState.enabled) {
return this.createMinimalSystemResponse(
`ℹ️ Gate system is already disabled.`,
"disable_gate_system"
);
}
await this.gateSystemManager.disableGateSystem(
args.reason || "User requested to disable gate system"
);
const response =
`⚠️ **Gate System Disabled**\n\n` +
`**Reason**: ${
args.reason || "User requested to disable gate system"
}\n` +
`**Status**: Gate system is now inactive\n` +
`**Impact**: Gate validation and guidance will be skipped\n\n` +
`📝 Prompt executions will now skip quality gate validation.`;
return this.createMinimalSystemResponse(response, "disable_gate_system");
}
/**
* Get gate system status
*/
public async getGateSystemStatus(): Promise<ToolResponse> {
if (!this.gateSystemManager) {
return this.createMinimalSystemResponse(
`❌ Gate system manager not available.`,
"gate_system_status"
);
}
const currentState = this.gateSystemManager.getCurrentState();
const health = this.gateSystemManager.getSystemHealth();
let response = `🚪 **Gate System Status**\n\n`;
response += `**System State**: ${
currentState.enabled ? "Enabled" : "Disabled"
}\n`;
response += `**Health Status**: ${health.status}\n`;
response += `**Total Validations**: ${health.totalValidations}\n`;
response += `**Success Rate**: ${health.successRate}%\n`;
response += `**Average Validation Time**: ${health.averageValidationTime}ms\n`;
if (health.lastValidationTime) {
response += `**Last Validation**: ${health.lastValidationTime.toISOString()}\n`;
}
if (health.issues.length > 0) {
response += `\n⚠️ **Issues**:\n`;
health.issues.forEach((issue) => {
response += `- ${issue}\n`;
});
}
response += `\n🔧 Control gates using: action="gates", operation="enable/disable"`;
return this.createMinimalSystemResponse(response, "gate_system_status");
}
/**
* Get gate system health details
*/
public async getGateSystemHealth(): Promise<ToolResponse> {
if (!this.gateSystemManager) {
return this.createMinimalSystemResponse(
`❌ Gate system manager not available.`,
"gate_system_health"
);
}
const health = this.gateSystemManager.getSystemHealth();
let response = `🏥 **Gate System Health Report**\n\n`;
// Health status indicator
const statusIcon =
health.status === "healthy"
? "✅"
: health.status === "degraded"
? "⚠️"
: "❌";
response += `**Overall Status**: ${statusIcon} ${health.status.toUpperCase()}\n\n`;
// Core metrics
response += `**Performance Metrics**:\n`;
response += `- Enabled: ${health.enabled ? "Yes" : "No"}\n`;
response += `- Total Validations: ${health.totalValidations}\n`;
response += `- Success Rate: ${health.successRate}%\n`;
response += `- Average Validation Time: ${health.averageValidationTime}ms\n`;
if (health.lastValidationTime) {
response += `- Last Validation: ${health.lastValidationTime.toISOString()}\n`;
}
// Health analysis
if (health.status === "healthy") {
response += "\n✅ System is performing optimally. No action required.\n";
} else if (health.status === "degraded") {
response += "\n⚠️ System performance is degraded. Monitor closely.\n";
if (health.issues.length > 0) {
response += "\n**Issues Detected**:\n";
health.issues.forEach((issue) => {
response += `- ${issue}\n`;
});
}
} else if (health.status === "disabled") {
response += "\n🚫 Gate system is currently disabled.\n";
response += "Enable using: `action='gates', operation='enable'`\n";
}
return this.createMinimalSystemResponse(response, "gate_system_health");
}
/**
* List all available quality gates
*/
async listAvailableGates(): Promise<ToolResponse> {
const gates =
(await this.gateGuidanceRenderer?.getAvailableGates()) || [];
const gateList = gates.length
? gates.map((gate) => `• ${gate}`).join("\n")
: "• No quality gates discovered. Ensure gate configuration is available.";
const exampleGate = gates[0] || "gate-name";
const response = [
"📋 **Available Quality Gates**",
"",
"Discover gates using: `system_control({ action: \"gates\", operation: \"list\" })`",
"",
gateList,
"",
"**Usage**: Specify gate names in prompt_engine's `quality_gates` parameter",
`**Example**: \`{ \\\"quality_gates\\\": [\"${exampleGate}\"], \\\"gate_mode\\\": \"enforce\" }\``,
].join("\n");
return this.createMinimalSystemResponse(response, "gate_list");
}
public async resetMetrics(args: any): Promise<ToolResponse> {
throw new Error("resetMetrics method not yet implemented");
}
public async getSwitchHistory(args: any): Promise<ToolResponse> {
throw new Error("getSwitchHistory method not yet implemented");
}
public async getAnalytics(args: any): Promise<ToolResponse> {
throw new Error("getAnalytics method not yet implemented");
}
public async restoreConfig(args: any): Promise<ToolResponse> {
throw new Error("restoreConfig method not yet implemented");
}
public async manageConfig(args: any): Promise<ToolResponse> {
throw new Error("manageConfig method not yet implemented");
}
public async restartServer(args: any): Promise<ToolResponse> {
throw new Error("restartServer method not yet implemented");
}
}
/**
* Base class for action handlers using command pattern
*/
abstract class ActionHandler {
constructor(protected systemControl: ConsolidatedSystemControl) {}
abstract execute(args: any): Promise<ToolResponse>;
// Convenience getters for accessing system control properties
protected get responseFormatter() {
return this.systemControl["responseFormatter"];
}
protected get logger() {
return this.systemControl["logger"];
}
protected get startTime() {
return this.systemControl.startTime;
}
protected get frameworkManager() {
return this.systemControl["frameworkManager"];
}
protected get mcpToolsManager() {
return this.systemControl["mcpToolsManager"];
}
protected get configManager() {
return this.systemControl["configManager"];
}
protected get safeConfigWriter() {
return this.systemControl["safeConfigWriter"];
}
protected get onRestart() {
return this.systemControl["onRestart"];
}
// Helper methods for system status and formatting
protected createMinimalSystemResponse(
text: string,
action: string
): ToolResponse {
return createStructuredResponse(text, false, {
action,
systemState: {
uptime: Date.now() - this.startTime,
framework:
this.systemControl.frameworkStateManager?.getCurrentState()
.activeFramework,
},
});
}
protected getExecutionsByMode(): Record<string, number> {
// Extract execution mode data from performance trends
const modeData: Record<string, number> = {};
this.systemControl.systemAnalytics.performanceTrends.forEach((trend) => {
if (trend.executionMode) {
modeData[trend.executionMode] =
(modeData[trend.executionMode] || 0) + 1;
}
});
return modeData;
}
protected formatUptime(uptime: number): string {
const seconds = Math.floor(uptime / 1000);
const minutes = Math.floor(seconds / 60);
const hours = Math.floor(minutes / 60);
const days = Math.floor(hours / 24);
if (days > 0) return `${days}d ${hours % 24}h ${minutes % 60}m`;
if (hours > 0) return `${hours}h ${minutes % 60}m`;
if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
return `${seconds}s`;
}
protected formatExecutionTime(time: number): string {
return `${Math.round(time)}ms`;
}
protected formatBytes(bytes: number): string {
const units = ["B", "KB", "MB", "GB"];
let value = bytes;
let unitIndex = 0;
while (value >= 1024 && unitIndex < units.length - 1) {
value /= 1024;
unitIndex++;
}
return `${Math.round(value * 100) / 100}${units[unitIndex]}`;
}
protected getHealthIcon(status: string): string {
switch (status) {
case "healthy":
return "✅";
case "warning":
return "⚠️";
case "error":
return "❌";
case "critical":
return "🚨";
default:
return "❓";
}
}
protected getSuccessRate(): number {
const total = this.systemControl.systemAnalytics.totalExecutions;
if (total === 0) return 100;
return Math.round(
(this.systemControl.systemAnalytics.successfulExecutions / total) * 100
);
}
protected formatTrendContext(trend: any): string {
let context = "";
if (trend.framework) context += ` [${trend.framework}]`;
if (trend.executionMode) context += ` (${trend.executionMode})`;
if (trend.success !== undefined) context += trend.success ? " ✓" : " ✗";
return context;
}
protected formatTrendValue(metric: string, value: number): string {
switch (metric) {
case "executionTime":
return `${Math.round(value)}ms`;
case "memoryDelta":
return `${value > 0 ? "+" : ""}${this.formatBytes(value)}`;
case "successRate":
return `${Math.round(value * 100)}%`;
case "gateValidationTime":
return `${Math.round(value)}ms validation`;
default:
return String(value);
}
}
}
/**
* Handler for status-related operations
*/
class StatusActionHandler extends ActionHandler {
async execute(args: any): Promise<ToolResponse> {
const operation = args.operation || "default";
switch (operation) {
case "health":
return await this.getSystemHealthStatus();
case "diagnostics":
return await this.getSystemDiagnostics();
case "framework_status":
return await this.getFrameworkStatus();
case "overview":
case "default":
default:
return await this.systemControl.getSystemStatus({
include_history: args.include_history,
include_metrics: args.include_metrics,
});
}
}
private async getSystemHealthStatus(): Promise<ToolResponse> {
if (!this.systemControl.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const health = this.systemControl.frameworkStateManager.getSystemHealth();
const statusIcon = health.status === "healthy" ? "✅" : "⚠️";
let response = `${statusIcon} **System Health Status**: ${health.status}\n\n`;
response += `📊 **Metrics**:\n`;
// Improved framework status display
const isFrameworkEnabled = health.frameworkSystemEnabled;
const injectionStatus = isFrameworkEnabled ? "Working" : "Inactive";
const frameworkStatusText = isFrameworkEnabled
? `✅ Enabled - ${health.activeFramework} methodology active`
: `🚫 Disabled - ${health.activeFramework} selected but not injecting`;
response += `- Framework System: ${frameworkStatusText}\n`;
response += `- Framework Injection: ${injectionStatus}\n`;
response += `- Available Frameworks: ${health.availableFrameworks.join(
", "
)}\n`;
response += `- Total Framework Switches: ${health.switchingMetrics.totalSwitches}\n`;
return this.createMinimalSystemResponse(response, "health");
}
private async getSystemDiagnostics(): Promise<ToolResponse> {
let response = `🔧 **System Diagnostics**\n\n`;
try {
if (this.systemControl.frameworkStateManager) {
const health =
this.systemControl.frameworkStateManager.getSystemHealth();
response += `Framework State: ${health.status}\n`;
response += `Active Framework: ${health.activeFramework}\n`;
}
response += `Server Uptime: ${
Date.now() - this.systemControl.startTime
}ms\n`;
} catch (error) {
response += `❌ Error during diagnostics: ${error}\n`;
}
return this.createMinimalSystemResponse(response, "diagnostics");
}
private async getFrameworkStatus(): Promise<ToolResponse> {
if (!this.systemControl.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const health = this.systemControl.frameworkStateManager.getSystemHealth();
let response = `🎯 **Framework System Status**\n\n`;
// Enhanced status display
const isFrameworkEnabled = health.frameworkSystemEnabled;
const injectionStatusIcon = isFrameworkEnabled ? "✅" : "🚫";
const injectionStatusText = isFrameworkEnabled
? "Active - Framework guidance being applied"
: "Inactive - Framework guidance disabled";
response += `**Selected Framework**: ${health.activeFramework}\n`;
response += `**Injection Status**: ${injectionStatusIcon} ${injectionStatusText}\n`;
response += `**System State**: ${
health.frameworkSystemEnabled ? "Enabled" : "Disabled"
}\n`;
response += `**Health Status**: ${health.status}\n`;
response += `**Available Frameworks**: ${health.availableFrameworks.join(
", "
)}\n`;
// Add warning for confused state
if (!isFrameworkEnabled && health.activeFramework) {
response += `\n⚠️ **Warning**: Framework system is disabled while ${health.activeFramework} is selected.\n`;
response += `This means prompts will NOT receive framework methodology guidance.\n`;
response += `To enable framework injection, use: \`system_control framework enable\`\n`;
}
return this.createMinimalSystemResponse(response, "framework_status");
}
}
/**
* Handler for framework-related operations
*/
class FrameworkActionHandler extends ActionHandler {
async execute(args: any): Promise<ToolResponse> {
const operation = args.operation || "default";
switch (operation) {
case "switch":
return await this.systemControl.switchFramework({
framework: args.framework,
reason: args.reason,
});
case "list":
return await this.systemControl.listFrameworks({
show_details: args.show_details,
});
case "enable":
return await this.systemControl.enableFrameworkSystem({
reason: args.reason,
});
case "disable":
return await this.systemControl.disableFrameworkSystem({
reason: args.reason,
});
default:
throw new Error(
`Unknown framework operation: ${operation}. Valid operations: switch, list, enable, disable`
);
}
}
}
/**
* Handler for gates-related operations
*/
class GateActionHandler extends ActionHandler {
async execute(args: any): Promise<ToolResponse> {
const operation = args.operation || "status";
switch (operation) {
case "enable":
return await this.systemControl.enableGateSystem({
reason: args.reason,
});
case "disable":
return await this.systemControl.disableGateSystem({
reason: args.reason,
});
case "status":
return await this.systemControl.getGateSystemStatus();
case "health":
return await this.systemControl.getGateSystemHealth();
case "list":
return await this.systemControl.listAvailableGates();
default:
throw new Error(
`Unknown gates operation: ${operation}. Valid operations: enable, disable, status, health, list`
);
}
}
}
/**
* Handler for analytics-related operations
*/
class AnalyticsActionHandler extends ActionHandler {
async execute(args: any): Promise<ToolResponse> {
const operation = args.operation || "default";
switch (operation) {
case "reset":
return await this.systemControl.resetMetrics({
confirm: args.confirm,
});
case "history":
return await this.systemControl.getSwitchHistory({
limit: args.limit,
});
case "view":
case "default":
default:
return await this.systemControl.getAnalytics({
include_history: args.include_history,
reset_analytics: args.reset_analytics,
});
}
}
}
/**
* Handler for config-related operations
*/
class ConfigActionHandler extends ActionHandler {
async execute(args: any): Promise<ToolResponse> {
const operation = args.operation || "default";
switch (operation) {
case "restore":
return await this.systemControl.restoreConfig({
backup_path: args.backup_path,
confirm: args.confirm,
});
case "get":
case "set":
case "list":
case "validate":
case "default":
default:
return await this.systemControl.manageConfig({
config: args.config,
});
}
}
}
/**
* Handler for maintenance-related operations
*/
class MaintenanceActionHandler extends ActionHandler {
async execute(args: any): Promise<ToolResponse> {
const operation = args.operation || "default";
switch (operation) {
case "restart":
case "default":
default:
return await this.systemControl.restartServer({
reason: args.reason,
confirm: args.confirm,
});
}
}
/**
* Get comprehensive system status
*/
public async getSystemStatus(args: {
include_history?: boolean;
include_metrics?: boolean;
}): Promise<ToolResponse> {
const { include_history = false, include_metrics = true } = args;
if (!this.systemControl.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const currentState =
this.systemControl.frameworkStateManager.getCurrentState();
const systemHealth =
this.systemControl.frameworkStateManager.getSystemHealth();
const activeFramework =
this.systemControl.frameworkStateManager.getActiveFramework();
let response = "# ⚙️ System Status Report\n\n";
// Framework Status
response += "## 📋 Framework Status\n\n";
response += `**Active Framework**: ${activeFramework.name} (${activeFramework.id})\n`;
response += `**Description**: ${activeFramework.description}\n`;
response += `**System Health**: ${this.getHealthIcon(
systemHealth.status
)} ${systemHealth.status.toUpperCase()}\n`;
response += `**Last Switch**: ${currentState.switchedAt.toISOString()}\n`;
response += `**Switch Reason**: ${currentState.switchReason}\n\n`;
// Gate System Status
if (this.systemControl.gateSystemManager) {
const gateHealth = this.systemControl.gateSystemManager.getSystemHealth();
response += "## 🚪 Gate System Status\n\n";
response += `**System State**: ${
gateHealth.enabled ? "Enabled" : "Disabled"
}\n`;
response += `**Health Status**: ${this.getHealthIcon(
gateHealth.status
)} ${gateHealth.status.toUpperCase()}\n`;
response += `**Total Validations**: ${gateHealth.totalValidations}\n`;
response += `**Success Rate**: ${gateHealth.successRate}%\n`;
if (gateHealth.lastValidationTime) {
response += `**Last Validation**: ${gateHealth.lastValidationTime.toISOString()}\n`;
}
response += `\n`;
} else {
response += "## 🚪 Gate System Status\n\n";
response += `**System State**: Not Available\n`;
response += `**Note**: Gate system manager not initialized\n\n`;
}
// System Metrics
response += "## 📊 System Metrics\n\n";
response += `**Uptime**: ${this.formatUptime(
this.systemControl.systemAnalytics.uptime
)}\n`;
response += `**Total Executions**: ${this.systemControl.systemAnalytics.totalExecutions}\n`;
response += `**Success Rate**: ${this.getSuccessRate()}%\n`;
response += `**Average Execution Time**: ${this.formatExecutionTime(
this.systemControl.systemAnalytics.averageExecutionTime
)}\n`;
if (this.systemControl.systemAnalytics.memoryUsage) {
const mem = this.systemControl.systemAnalytics.memoryUsage;
response += `**Memory Usage**: ${this.formatBytes(
mem.heapUsed
)}/${this.formatBytes(mem.heapTotal)}\n`;
}
response += `\n`;
// Available Frameworks
const availableFrameworks =
this.systemControl.frameworkStateManager.getAvailableFrameworks();
response += "## 🔄 Available Frameworks\n\n";
availableFrameworks.forEach((framework) => {
const isActive = framework.id === currentState.activeFramework;
const icon = isActive ? "🟢" : "⚪";
response += `${icon} **${framework.name}** - ${framework.description}\n`;
});
response += "\n";
// Performance Metrics
if (include_metrics) {
response += "## 🎯 Performance Breakdown\n\n";
const switchingMetrics = systemHealth.switchingMetrics;
response += `**Framework Switches**: ${switchingMetrics.totalSwitches}\n`;
response += `**Framework Switch Success Rate**: ${
switchingMetrics.totalSwitches > 0
? Math.round(
(switchingMetrics.successfulSwitches /
switchingMetrics.totalSwitches) *
100
)
: 100
}%\n`;
response += `**Framework Switch Time**: ${Math.round(
switchingMetrics.averageResponseTime
)}ms\n`;
response += `\n**Execution Modes**:\n`;
const executionsByMode = this.getExecutionsByMode();
Object.entries(executionsByMode).forEach(([mode, count]) => {
response += `- ${
mode.charAt(0).toUpperCase() + mode.slice(1)
}: ${count} executions\n`;
});
response += `\n`;
}
// System Health Issues
if (systemHealth.issues.length > 0) {
response += "## ⚠️ System Issues\n\n";
systemHealth.issues.forEach((issue) => {
response += `- ⚠️ ${issue}\n`;
});
response += "\n";
}
// Recent Activity
if (
include_history &&
this.systemControl.systemAnalytics.performanceTrends.length > 0
) {
response += "## 📈 Recent Performance Trends\n\n";
const recentTrends =
this.systemControl.systemAnalytics.performanceTrends.slice(-10);
recentTrends.forEach((trend, index) => {
const timestamp = new Date(trend.timestamp)
.toISOString()
.split("T")[1]
.split(".")[0];
const contextInfo = this.formatTrendContext(trend);
response += `${index + 1}. ${timestamp}: ${this.formatTrendValue(
trend.metric,
trend.value
)}${contextInfo}\n`;
});
response += "\n";
}
// Control Commands
response += "## 🎛️ Available Commands\n\n";
response += "- `switch_framework` - Change active framework methodology\n";
response +=
"- `gates` - Control gate system (enable, disable, status, health)\n";
response += "- `analytics` - View detailed execution analytics\n";
response += "- `health` - Check system health status\n";
response += "- `diagnostics` - Run comprehensive system diagnostics\n";
response +=
"- `config` - Manage system configuration (get, set, list, validate)\n";
response += "- `config_restore` - Restore configuration from backup\n";
response += "- `reset_metrics` - Reset framework switching counters\n";
response += "- `switch_history` - View framework change history\n";
response += "- `restart` - Full server restart (requires confirmation)\n";
return this.responseFormatter.formatSystemControlResponse(
response,
"status",
{
frameworkEnabled: currentState.frameworkSystemEnabled,
activeFramework: activeFramework.name,
availableFrameworks:
this.frameworkManager?.listFrameworks().map((f: any) => f.name) || [],
uptime: (Date.now() - this.startTime) / 1000,
memoryUsage: process.memoryUsage ? process.memoryUsage() : undefined,
serverHealth: systemHealth.status as
| "healthy"
| "warning"
| "error"
| "critical",
lastFrameworkSwitch: currentState.switchedAt.toISOString(),
},
undefined,
{
includeStructuredData: true,
}
);
}
/**
* Switch framework
*/
public async switchFramework(args: {
framework?: "CAGEERF" | "ReACT" | "5W1H" | "SCAMPER";
reason?: string;
}): Promise<ToolResponse> {
if (!this.systemControl.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
if (!args.framework) {
throw new Error("Framework parameter is required for switch operation");
}
const { framework, reason = `User requested switch to ${args.framework}` } =
args;
const currentState =
this.systemControl.frameworkStateManager.getCurrentState();
// Check if already active
if (currentState.activeFramework === framework) {
return this.createMinimalSystemResponse(
`ℹ️ Framework '${framework}' is already active. No change needed.`,
"switch_framework"
);
}
const request: FrameworkSwitchRequest = {
targetFramework: framework,
reason: reason,
};
const success =
await this.systemControl.frameworkStateManager.switchFramework(request);
if (success) {
const newState =
this.systemControl.frameworkStateManager.getCurrentState();
const activeFramework =
this.systemControl.frameworkStateManager.getActiveFramework();
let response = `🔄 **Framework Switch Successful**\n\n`;
response += `**Previous**: ${currentState.activeFramework}\n`;
response += `**Current**: ${newState.activeFramework}\n`;
response += `**Switched At**: ${newState.switchedAt.toISOString()}\n`;
response += `**Reason**: ${reason}\n\n`;
response += `**New Framework Details**:\n`;
response += `- **Name**: ${activeFramework.name}\n`;
response += `- **Description**: ${activeFramework.description}\n`;
response += `- **Methodology**: ${activeFramework.methodology}\n\n`;
response += `**Guidelines**: ${activeFramework.executionGuidelines.join(
" • "
)}\n\n`;
response += `✅ All future prompt executions will now use the ${framework} methodology.`;
// Trigger dynamic tool description updates
if (this.mcpToolsManager?.reregisterToolsWithUpdatedDescriptions) {
try {
await this.mcpToolsManager.reregisterToolsWithUpdatedDescriptions();
response += `\n\n🔄 **Tool descriptions updated** - MCP clients will receive updated tool descriptions with ${framework} methodology guidance.`;
} catch (error) {
this.logger.error(
`Failed to update tool descriptions after framework switch: ${
error instanceof Error ? error.message : String(error)
}`
);
response += `\n\n⚠️ **Note**: Tool descriptions may need manual refresh for some clients.`;
}
}
return this.createMinimalSystemResponse(response, "switch_framework");
} else {
return this.createMinimalSystemResponse(
`❌ Failed to switch to framework '${framework}'. Check system logs for details.`,
"switch_framework"
);
}
}
/**
* List available frameworks
*/
public async listFrameworks(args: {
show_details?: boolean;
}): Promise<ToolResponse> {
if (!this.systemControl.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const { show_details = true } = args;
const currentState =
this.systemControl.frameworkStateManager.getCurrentState();
const availableFrameworks =
this.systemControl.frameworkStateManager.getAvailableFrameworks();
let response = "# 📋 Available Framework Methodologies\n\n";
response += `**Currently Active**: ${currentState.activeFramework}\n\n`;
availableFrameworks.forEach((framework) => {
const isActive = framework.id === currentState.activeFramework;
const icon = isActive ? "🟢" : "⚪";
const status = isActive ? " (ACTIVE)" : "";
response += `## ${icon} ${framework.name}${status}\n\n`;
response += `**ID**: ${framework.id}\n`;
response += `**Methodology**: ${framework.methodology}\n`;
response += `**Description**: ${framework.description}\n`;
response += `**Priority**: ${framework.priority}\n`;
response += `**Enabled**: ${framework.enabled ? "✅ Yes" : "❌ No"}\n`;
response += `**Applicable Types**: ${
framework.applicableTypes.join(", ") || "All"
}\n`;
if (show_details && framework.executionGuidelines) {
response += `\n**Execution Guidelines**:\n`;
framework.executionGuidelines.forEach((guideline, index) => {
response += `${index + 1}. ${guideline}\n`;
});
}
response += "\n";
});
response += "---\n\n";
response +=
"**Usage**: Use `switch_framework` action to change the active framework methodology.\n";
response +=
"**Note**: The framework methodology determines how prompts are processed systematically.";
return this.createMinimalSystemResponse(response, "list_frameworks");
}
/**
* Get execution analytics
*/
public async getAnalytics(args: {
include_history?: boolean;
reset_analytics?: boolean;
}): Promise<ToolResponse> {
const { include_history = false, reset_analytics = false } = args;
if (reset_analytics) {
this.resetAnalyticsData();
return this.createMinimalSystemResponse(
"📊 Analytics have been reset to zero.",
"analytics"
);
}
const successRate = this.getSuccessRate();
const avgTime = this.formatExecutionTime(
this.systemControl.systemAnalytics.averageExecutionTime
);
let response = "# 📊 System Analytics Report\n\n";
// Overall Performance
response += "## 📈 Overall Performance\n\n";
response += `**Total Executions**: ${this.systemControl.systemAnalytics.totalExecutions}\n`;
response += `**Success Rate**: ${successRate}%\n`;
response += `**Failed Executions**: ${this.systemControl.systemAnalytics.failedExecutions}\n`;
response += `**Average Execution Time**: ${avgTime}\n`;
response += `**System Uptime**: ${this.formatUptime(
this.systemControl.systemAnalytics.uptime
)}\n\n`;
// Execution Modes
response += "## 🎯 Execution Mode Distribution\n\n";
const executionsByMode = this.getExecutionsByMode();
const totalModeExecutions = Object.values(executionsByMode).reduce(
(a, b) => a + b,
0
);
Object.entries(executionsByMode).forEach(([mode, count]) => {
const percentage =
totalModeExecutions > 0
? Math.round((count / totalModeExecutions) * 100)
: 0;
response += `- **${
mode.charAt(0).toUpperCase() + mode.slice(1)
} Mode**: ${count} executions (${percentage}%)\n`;
});
response += "\n";
// Quality Gates (Phase 4: Enhanced with advanced analytics)
response += "## 🛡️ Quality Gate Analytics\n\n";
response += `**Gate Validations**: ${this.systemControl.systemAnalytics.gateValidationCount}\n`;
response += `**Gate Adoption Rate**: ${
this.systemControl.systemAnalytics.totalExecutions > 0
? Math.round(
(this.systemControl.systemAnalytics.gateValidationCount /
this.systemControl.systemAnalytics.totalExecutions) *
100
)
: 0
}%\n`;
// Phase 4: Clean architecture gate performance analytics
if (this.systemControl.gatePerformanceAnalyzer) {
try {
const gateAnalytics =
this.systemControl.gatePerformanceAnalyzer.getPerformanceAnalytics();
response += `**Advanced Gate System**: Enabled\n`;
response += `**Total Gates Tracked**: ${gateAnalytics.totalGates}\n`;
response += `**Average Gate Execution Time**: ${Math.round(
gateAnalytics.avgExecutionTime
)}ms\n`;
response += `**Overall Gate Success Rate**: ${Math.round(
gateAnalytics.overallSuccessRate * 100
)}%\n`;
if (gateAnalytics.topPerformingGates.length > 0) {
response += `**Top Performing Gates**: ${gateAnalytics.topPerformingGates.join(
", "
)}\n`;
}
if (gateAnalytics.underperformingGates.length > 0) {
response += `**Needs Optimization**: ${gateAnalytics.underperformingGates.join(
", "
)}\n`;
}
if (gateAnalytics.recommendations.length > 0) {
response += `\n**Optimization Recommendations**:\n`;
gateAnalytics.recommendations.forEach(
(rec: string, index: number) => {
response += `${index + 1}. ${rec}\n`;
}
);
}
} catch (error) {
response += `**Advanced Gate System**: Error retrieving analytics\n`;
}
} else {
response += `**Advanced Gate System**: Not available\n`;
}
response += "\n";
// System Resources
if (this.systemControl.systemAnalytics.memoryUsage) {
response += "## 💾 System Resources\n\n";
const mem = this.systemControl.systemAnalytics.memoryUsage;
response += `**Heap Used**: ${this.formatBytes(mem.heapUsed)}\n`;
response += `**Heap Total**: ${this.formatBytes(mem.heapTotal)}\n`;
response += `**RSS**: ${this.formatBytes(mem.rss)}\n`;
response += `**External**: ${this.formatBytes(mem.external)}\n\n`;
}
// Performance Trends
if (
include_history &&
this.systemControl.systemAnalytics.performanceTrends.length > 0
) {
response += "## 📈 Performance Trends\n\n";
// Group trends by metric type for better organization
const trendsByMetric =
this.systemControl.systemAnalytics.performanceTrends.reduce(
(acc, trend) => {
if (!acc[trend.metric]) acc[trend.metric] = [];
acc[trend.metric].push(trend);
return acc;
},
{} as Record<string, any[]>
);
Object.entries(trendsByMetric).forEach(([metric, trends]) => {
const recentTrends = trends.slice(-10);
response += `### ${
metric.charAt(0).toUpperCase() + metric.slice(1)
} Trends\n`;
recentTrends.forEach((trend, index) => {
const time = new Date(trend.timestamp)
.toISOString()
.split("T")[1]
.split(".")[0];
const contextInfo = this.formatTrendContext(trend);
response += `${index + 1}. ${time}: ${this.formatTrendValue(
trend.metric,
trend.value
)}${contextInfo}\n`;
});
response += "\n";
});
}
response += `\n---\n*Generated at: ${new Date().toISOString()}*`;
return this.createMinimalSystemResponse(response, "analytics");
}
/**
* Get system health
*/
public async getSystemHealth(args: any): Promise<ToolResponse> {
if (!this.systemControl.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const health = this.systemControl.frameworkStateManager.getSystemHealth();
const statusIcon = this.getHealthIcon(health.status);
let response = `# 🏥 System Health Report\n\n`;
response += `**Overall Status**: ${statusIcon} ${health.status.toUpperCase()}\n`;
response += `**Active Framework**: ${health.activeFramework}\n`;
response += `**Available Frameworks**: ${health.availableFrameworks.length}\n`;
response += `**System Uptime**: ${this.formatUptime(
this.systemControl.systemAnalytics.uptime
)}\n\n`;
// Performance Health
response += "## 📊 Performance Health\n\n";
response += `**Framework Switches**: ${health.switchingMetrics.totalSwitches}\n`;
response += `**Framework Switch Success Rate**: ${
health.switchingMetrics.totalSwitches > 0
? Math.round(
(health.switchingMetrics.successfulSwitches /
health.switchingMetrics.totalSwitches) *
100
)
: 100
}%\n`;
response += `**Framework Switch Time**: ${Math.round(
health.switchingMetrics.averageResponseTime
)}ms\n`;
response += `**Execution Success Rate**: ${this.getSuccessRate()}%\n\n`;
// Issues
if (health.issues.length > 0) {
response += "## ⚠️ Detected Issues\n\n";
health.issues.forEach((issue, index) => {
response += `${index + 1}. ⚠️ ${issue}\n`;
});
response += "\n";
} else {
response +=
"## ✅ System Status\n\nNo issues detected. System is operating normally.\n\n";
}
// Health Recommendations
response += "## 💡 Health Recommendations\n\n";
if (health.status === "healthy") {
response += "✅ System is healthy. No action required.\n";
response += "- Continue monitoring performance metrics\n";
response += "- Regular analytics reviews recommended\n";
} else if (health.status === "degraded") {
response += "⚠️ System performance is degraded. Monitor closely.\n";
response += "- Review recent framework switches for patterns\n";
response += "- Consider resetting metrics if issues are resolved\n";
response += "- Check execution failure rates\n";
} else {
response += "❌ System requires immediate attention.\n";
response += "- Check framework configuration\n";
response += "- Review system logs for error patterns\n";
response += "- Consider system restart if issues persist\n";
}
return this.createMinimalSystemResponse(response, "health");
}
/**
* Run comprehensive diagnostics
*/
public async runDiagnostics(args: any): Promise<ToolResponse> {
let response = "# 🔧 System Diagnostics Report\n\n";
// Framework System Check
response += "## 🔄 Framework System\n\n";
if (this.systemControl.frameworkStateManager) {
const state = this.systemControl.frameworkStateManager.getCurrentState();
const health = this.systemControl.frameworkStateManager.getSystemHealth();
const frameworks =
this.systemControl.frameworkStateManager.getAvailableFrameworks();
response += `✅ **Framework Manager**: Operational\n`;
response += `✅ **Active Framework**: ${state.activeFramework}\n`;
response += `✅ **Available Frameworks**: ${frameworks.length} configured\n`;
response += `${this.getHealthIcon(health.status)} **System Health**: ${
health.status
}\n\n`;
// Check each framework
frameworks.forEach((fw) => {
const icon = fw.enabled ? "✅" : "⚠️";
response += `${icon} **${fw.name}**: ${
fw.enabled ? "Enabled" : "Disabled"
}\n`;
});
response += "\n";
} else {
response += `❌ **Framework Manager**: Not initialized\n\n`;
}
// Performance Diagnostics
response += "## 📊 Performance Diagnostics\n\n";
response += `**Total Executions**: ${this.systemControl.systemAnalytics.totalExecutions}\n`;
response += `**Success Rate**: ${this.getSuccessRate()}%\n`;
response += `**Average Execution Time**: ${this.formatExecutionTime(
this.systemControl.systemAnalytics.averageExecutionTime
)}\n`;
// Performance Assessment
const successRate = this.getSuccessRate();
if (successRate >= 95) {
response += `✅ **Performance Assessment**: Excellent (${successRate}%)\n`;
} else if (successRate >= 85) {
response += `⚠️ **Performance Assessment**: Good (${successRate}%)\n`;
} else {
response += `❌ **Performance Assessment**: Needs attention (${successRate}%)\n`;
}
response += "\n";
// System Resources
response += "## 💾 System Resources\n\n";
if (this.systemControl.systemAnalytics.memoryUsage) {
const mem = this.systemControl.systemAnalytics.memoryUsage;
const heapUsagePercent = Math.round((mem.heapUsed / mem.heapTotal) * 100);
response += `**Memory Usage**: ${this.formatBytes(
mem.heapUsed
)}/${this.formatBytes(mem.heapTotal)} (${heapUsagePercent}%)\n`;
if (heapUsagePercent < 70) {
response += `✅ **Memory Status**: Healthy\n`;
} else if (heapUsagePercent < 90) {
response += `⚠️ **Memory Status**: Monitor usage\n`;
} else {
response += `❌ **Memory Status**: High usage - consider optimization\n`;
}
}
response += `**System Uptime**: ${this.formatUptime(
this.systemControl.systemAnalytics.uptime
)}\n\n`;
// Recommendations
response += "## 💡 Diagnostic Recommendations\n\n";
const recommendations: string[] = [];
if (this.getSuccessRate() < 90) {
recommendations.push(
"Investigate execution failure patterns to improve success rate"
);
}
if (this.systemControl.systemAnalytics.averageExecutionTime > 5000) {
recommendations.push(
"Consider optimizing execution performance - average time is high"
);
}
if (
this.systemControl.systemAnalytics.memoryUsage &&
this.systemControl.systemAnalytics.memoryUsage.heapUsed /
this.systemControl.systemAnalytics.memoryUsage.heapTotal >
0.8
) {
recommendations.push("Monitor memory usage - heap utilization is high");
}
if (recommendations.length > 0) {
recommendations.forEach((rec, index) => {
response += `${index + 1}. ${rec}\n`;
});
} else {
response += "✅ No issues detected. System is operating optimally.\n";
}
response += `\n---\n*Diagnostics completed at: ${new Date().toISOString()}*`;
return this.createMinimalSystemResponse(response, "diagnostics");
}
/**
* Reset framework switching metrics
*/
public async resetMetrics(args: {
confirm?: boolean;
}): Promise<ToolResponse> {
if (!args.confirm) {
return this.createMinimalSystemResponse(
"❌ Metrics reset cancelled. Set 'confirm: true' to reset all switching performance metrics.",
"reset_metrics"
);
}
const beforeMetrics = { ...this.systemControl.systemAnalytics };
this.resetAnalyticsData();
if (this.systemControl.frameworkStateManager) {
this.systemControl.frameworkStateManager.resetMetrics();
}
let response = `# 🔄 Metrics Reset Completed\n\n`;
response += `**Reset Timestamp**: ${new Date().toISOString()}\n\n`;
response += "## Metrics Before Reset\n\n";
response += `**Total Executions**: ${beforeMetrics.totalExecutions}\n`;
response += `**Successful**: ${beforeMetrics.successfulExecutions}\n`;
response += `**Failed**: ${beforeMetrics.failedExecutions}\n`;
response += `**Average Time**: ${this.formatExecutionTime(
beforeMetrics.averageExecutionTime
)}\n\n`;
response += "## Metrics After Reset\n\n";
response += `**Total Executions**: ${this.systemControl.systemAnalytics.totalExecutions}\n`;
response += `**Successful**: ${this.systemControl.systemAnalytics.successfulExecutions}\n`;
response += `**Failed**: ${this.systemControl.systemAnalytics.failedExecutions}\n`;
response += `**Average Time**: ${this.formatExecutionTime(
this.systemControl.systemAnalytics.averageExecutionTime
)}\n\n`;
response +=
"✅ All switching performance metrics have been reset. Framework switching monitoring will start fresh.";
return this.createMinimalSystemResponse(response, "reset_metrics");
}
/**
* Get framework switch history
*/
public async getSwitchHistory(args: {
limit?: number;
}): Promise<ToolResponse> {
if (!this.systemControl.frameworkStateManager) {
throw new Error("Framework state manager not initialized");
}
const { limit = 20 } = args;
const history =
this.systemControl.frameworkStateManager.getSwitchHistory(limit);
const currentState =
this.systemControl.frameworkStateManager.getCurrentState();
let response = `# 📈 Framework Switch History\n\n`;
response += `**Current Framework**: ${currentState.activeFramework}\n`;
response += `**History Entries**: ${history.length}\n\n`;
if (history.length === 0) {
response += "No framework switches recorded yet.\n\n";
} else {
response += "## Recent Switches\n\n";
history.forEach((entry, index) => {
response += `### ${index + 1}. ${entry.from} → ${entry.to}\n\n`;
response += `**Timestamp**: ${entry.timestamp.toISOString()}\n`;
response += `**Reason**: ${entry.reason}\n\n`;
});
}
response += "---\n\n";
response +=
"**Note**: This history helps track framework usage patterns and audit changes.";
return this.createMinimalSystemResponse(response, "switch_history");
}
/**
* Manage system configuration
*/
public async manageConfig(args: {
config?: {
key: string;
value?: string;
operation: "get" | "set" | "list" | "validate";
};
}): Promise<ToolResponse> {
const configRequest = args.config;
// Check if ConfigManager is available
if (!this.configManager) {
return createStructuredResponse(
"❌ **Configuration Manager Unavailable**\n\n" +
"ConfigManager is not initialized. This indicates a system initialization issue.\n" +
"Configuration management requires proper system startup.",
{ operation: "config", error: "config_manager_unavailable" },
true
);
}
try {
// Handle different config operations
if (!configRequest) {
return await this.handleConfigList();
}
switch (configRequest.operation) {
case "list":
return await this.handleConfigList();
case "get":
return await this.handleConfigGet(configRequest.key);
case "set":
return await this.handleConfigSet(
configRequest.key,
configRequest.value || ""
);
case "validate":
return await this.handleConfigValidate(
configRequest.key,
configRequest.value || ""
);
default:
throw new Error(
`Unknown config operation: ${configRequest.operation}`
);
}
} catch (error) {
return this.handleError(error, "config_management");
}
}
/**
* Handle config list operation
*/
private async handleConfigList(): Promise<ToolResponse> {
const config = this.configManager!.getConfig();
let response = "# ⚙️ System Configuration Overview\n\n";
// Server Configuration
response += "## 🖥️ Server Configuration\n\n";
response += `**Name**: ${config.server.name}\n`;
response += `**Version**: ${config.server.version}\n`;
response += `**Port**: ${config.server.port}\n\n`;
// Transport Configuration
response += "## 🚀 Transport Configuration\n\n";
response += `**Default Transport**: ${config.transports.default}\n`;
response += `**STDIO Enabled**: ${
config.transports.stdio.enabled ? "✅" : "❌"
}\n`;
response += `**SSE Enabled**: ${
config.transports.sse.enabled ? "✅" : "❌"
}\n\n`;
// Analysis Configuration
if (config.analysis) {
response += "## 🔍 Analysis Configuration\n\n";
response += `**LLM Integration**: ${
config.analysis.semanticAnalysis.llmIntegration.enabled ? "✅" : "❌"
}\n`;
if (config.analysis.semanticAnalysis.llmIntegration.enabled) {
response += `**Model**: ${config.analysis.semanticAnalysis.llmIntegration.model}\n`;
response += `**Max Tokens**: ${config.analysis.semanticAnalysis.llmIntegration.maxTokens}\n`;
response += `**Temperature**: ${config.analysis.semanticAnalysis.llmIntegration.temperature}\n`;
}
response += "\n";
}
// Logging Configuration
if (config.logging) {
response += "## 📝 Logging Configuration\n\n";
response += `**Directory**: ${config.logging.directory}\n`;
response += `**Level**: ${config.logging.level}\n\n`;
}
// Runtime Status
response += "## 📊 Runtime Status\n\n";
response += `**Framework System**: ${
this.systemControl.frameworkStateManager ? "✅ Enabled" : "❌ Disabled"
}\n`;
response += `**Analytics Collection**: ✅ Enabled\n`;
response += `**Performance Monitoring**: ✅ Enabled\n`;
response += `**System Uptime**: ${this.formatUptime(
this.systemControl.systemAnalytics.uptime
)}\n`;
response += `**Start Time**: ${new Date(this.startTime).toISOString()}\n\n`;
// Available Operations
response += "## 🔧 Available Configuration Keys\n\n";
response += "**Server Configuration:**\n";
response += "- `server.name` (string) - Server display name\n";
response += "- `server.version` (string) - Server version\n";
response +=
"- `server.port` (number) - HTTP server port ⚠️ *restart required*\n\n";
response += "**Transport Configuration:**\n";
response +=
"- `transports.default` (string) - Default transport ⚠️ *restart required*\n";
response +=
"- `transports.stdio.enabled` (boolean) - STDIO transport ⚠️ *restart required*\n";
response +=
"- `transports.sse.enabled` (boolean) - SSE transport ⚠️ *restart required*\n\n";
response += "**Logging Configuration:**\n";
response +=
"- `logging.level` (string) - Log level: debug, info, warn, error\n";
response += "- `logging.directory` (string) - Log file directory\n\n";
response += "**Usage Examples:**\n";
response +=
'- Get value: `{ "config": { "key": "server.port", "operation": "get" } }`\n';
response +=
'- Set value: `{ "config": { "key": "logging.level", "value": "debug", "operation": "set" } }`\n';
response +=
'- Validate: `{ "config": { "key": "server.port", "value": "3000", "operation": "validate" } }`';
return this.createMinimalSystemResponse(response, "config");
}
/**
* Handle config get operation
*/
private async handleConfigGet(key: string): Promise<ToolResponse> {
if (!key) {
throw new Error("Configuration key is required for get operation");
}
const value = this.getConfigValue(key);
if (value === undefined) {
return createStructuredResponse(
`❌ **Configuration Key Not Found**\n\n` +
`The key \`${key}\` does not exist in the configuration.\n\n` +
`Use the \`list\` operation to see available configuration keys.`,
{ operation: "config_get", key, error: "key_not_found" },
true
);
}
let response = `# 🔍 Configuration Value\n\n`;
response += `**Key**: \`${key}\`\n`;
response += `**Current Value**: \`${JSON.stringify(value)}\`\n`;
response += `**Type**: ${typeof value}\n\n`;
if (this.requiresRestart(key)) {
response += `⚠️ **Restart Required**: Changes to this setting require a server restart to take effect.\n\n`;
} else {
response += `✅ **Runtime Changeable**: This setting can be changed without restart.\n\n`;
}
response += `**Usage**: To modify this value, use:\n`;
response += `\`{ "config": { "key": "${key}", "value": "new_value", "operation": "set" } }\``;
return this.createMinimalSystemResponse(response, "config");
}
/**
* Handle config set operation
*/
private async handleConfigSet(
key: string,
value: string
): Promise<ToolResponse> {
if (!key || value === undefined) {
throw new Error("Both key and value are required for set operation");
}
// Check if SafeConfigWriter is available
if (!this.safeConfigWriter) {
return createStructuredResponse(
`⚠️ **Configuration Writing Unavailable**\n\n` +
`Configuration writing is not available (SafeConfigWriter not initialized).\n` +
`This may indicate a file system permission issue or invalid configuration path.\n\n` +
`**Key**: \`${key}\`\n` +
`**Value**: \`${value}\`\n\n` +
`**Fallback**: Use the \`validate\` operation to check if your change would be valid.`,
{
operation: "config_set",
key,
value,
error: "config_writer_unavailable",
},
true
);
}
// First validate the new value
const validation = this.validateConfigValue(key, value);
if (!validation.valid) {
return {
content: [
{
type: "text",
text:
`❌ **Invalid Configuration Value**\n\n` +
`**Key**: \`${key}\`\n` +
`**Value**: \`${value}\`\n` +
`**Error**: ${validation.error}\n\n` +
`${
validation.suggestion
? `**Suggestion**: ${validation.suggestion}`
: ""
}`,
},
],
isError: true,
};
}
try {
// Perform the actual configuration update
const currentValue = this.getConfigValue(key);
const writeResult = await this.safeConfigWriter.updateConfigValue(
key,
value
);
if (!writeResult.success) {
return {
content: [
{
type: "text",
text:
`❌ **Configuration Update Failed**\n\n` +
`**Key**: \`${key}\`\n` +
`**Value**: \`${value}\`\n` +
`**Error**: ${writeResult.error || writeResult.message}\n\n` +
`${
writeResult.backupPath
? `**Backup**: ${writeResult.backupPath}\n`
: ""
}` +
`**Current Value**: \`${JSON.stringify(
currentValue
)}\` (unchanged)\n\n` +
`**Note**: Configuration file has been left unchanged. No restart required.`,
},
],
isError: true,
};
}
// Success! Configuration has been updated
let response = `✅ **Configuration Updated Successfully**\n\n`;
response += `**Key**: \`${key}\`\n`;
response += `**Previous Value**: \`${JSON.stringify(currentValue)}\`\n`;
response += `**New Value**: \`${value}\`\n`;
response += `**Backup Created**: \`${writeResult.backupPath}\`\n\n`;
if (writeResult.restartRequired) {
response += `⚠️ **Server Restart Required**\n\n`;
response += `This configuration change requires a server restart to take effect.\n`;
response += `Use the \`restart\` action with \`confirm: true\` to restart the server.\n\n`;
response += `**Alternative**: The configuration file has been updated and will take effect on next startup.`;
} else {
response += `✅ **Change Applied Immediately**\n\n`;
response += `This configuration change has been applied and is now active.\n`;
response += `No server restart is required.`;
}
response += `\n\n**Recovery**: If needed, you can restore the previous configuration using:\n`;
response += `\`{ "action": "config_restore", "backup_path": "${writeResult.backupPath}" }\``;
return this.createMinimalSystemResponse(response, "config");
} catch (error) {
this.logger.error(
`Unexpected error during config set for ${key}:`,
error
);
return {
content: [
{
type: "text",
text:
`❌ **Unexpected Configuration Error**\n\n` +
`**Key**: \`${key}\`\n` +
`**Value**: \`${value}\`\n` +
`**Error**: ${String(error)}\n\n` +
`**Status**: Configuration unchanged. System remains stable.\n` +
`**Action**: Check system logs for detailed error information.`,
},
],
isError: true,
};
}
}
/**
* Handle config validate operation
*/
private async handleConfigValidate(
key: string,
value: string
): Promise<ToolResponse> {
if (!key || value === undefined) {
throw new Error("Both key and value are required for validate operation");
}
const validation = this.validateConfigValue(key, value);
const currentValue = this.getConfigValue(key);
let response = `# 🔍 Configuration Validation\n\n`;
response += `**Key**: \`${key}\`\n`;
response += `**Proposed Value**: \`${value}\`\n`;
response += `**Current Value**: \`${JSON.stringify(currentValue)}\`\n`;
response += `**Valid**: ${validation.valid ? "✅ Yes" : "❌ No"}\n\n`;
if (!validation.valid) {
response += `**Error**: ${validation.error}\n`;
if (validation.suggestion) {
response += `**Suggestion**: ${validation.suggestion}\n`;
}
} else {
response += `**Type**: ${validation.type}\n`;
response += `**Restart Required**: ${
this.requiresRestart(key) ? "⚠️ Yes" : "✅ No"
}\n`;
}
return this.createMinimalSystemResponse(response, "config");
}
/**
* Get configuration value using dot notation
*/
private getConfigValue(key: string): any {
const config = this.configManager!.getConfig();
const parts = key.split(".");
let value: any = config;
for (const part of parts) {
if (value && typeof value === "object" && part in value) {
value = value[part];
} else {
return undefined;
}
}
return value;
}
/**
* Validate configuration value
*/
private validateConfigValue(
key: string,
value: string
): { valid: boolean; error?: string; suggestion?: string; type?: string } {
// Basic key validation
if (!this.isValidConfigKey(key)) {
return {
valid: false,
error: `Unknown configuration key: ${key}`,
suggestion: "Use the 'list' operation to see available keys",
};
}
// Type-specific validation
try {
switch (key) {
case "server.port":
const port = parseInt(value, 10);
if (isNaN(port) || port < 1024 || port > 65535) {
return {
valid: false,
error: "Port must be a number between 1024-65535",
suggestion: "Try a value like 3000 or 8080",
};
}
return { valid: true, type: "number" };
case "server.name":
case "server.version":
if (!value || value.trim().length === 0) {
return {
valid: false,
error: "Value cannot be empty",
suggestion: "Provide a non-empty string value",
};
}
return { valid: true, type: "string" };
case "transports.default":
if (!["stdio", "sse"].includes(value)) {
return {
valid: false,
error: "Transport must be 'stdio' or 'sse'",
suggestion:
"Use 'stdio' for desktop clients or 'sse' for web clients",
};
}
return { valid: true, type: "string" };
case "transports.stdio.enabled":
case "transports.sse.enabled":
if (!["true", "false"].includes(value.toLowerCase())) {
return {
valid: false,
error: "Value must be 'true' or 'false'",
suggestion: "Use boolean values: true or false",
};
}
return { valid: true, type: "boolean" };
case "logging.level":
if (!["debug", "info", "warn", "error"].includes(value)) {
return {
valid: false,
error: "Log level must be: debug, info, warn, or error",
suggestion:
"Use 'debug' for development or 'info' for production",
};
}
return { valid: true, type: "string" };
case "logging.directory":
if (!value || value.trim().length === 0) {
return {
valid: false,
error: "Directory path cannot be empty",
suggestion: "Provide a valid directory path like './logs'",
};
}
return { valid: true, type: "string" };
default:
return { valid: true, type: "unknown" };
}
} catch (error) {
return {
valid: false,
error: `Validation error: ${error}`,
suggestion: "Check the value format and try again",
};
}
}
/**
* Check if config key is valid
*/
private isValidConfigKey(key: string): boolean {
const validKeys = [
"server.name",
"server.version",
"server.port",
"transports.default",
"transports.stdio.enabled",
"transports.sse.enabled",
"logging.level",
"logging.directory",
"analysis.semanticAnalysis.llmIntegration.enabled",
"analysis.semanticAnalysis.llmIntegration.model",
"analysis.semanticAnalysis.llmIntegration.maxTokens",
"analysis.semanticAnalysis.llmIntegration.temperature",
];
return validKeys.includes(key);
}
/**
* Check if config key requires restart
*/
private requiresRestart(key: string): boolean {
const restartRequired = [
"server.port",
"transports.default",
"transports.stdio.enabled",
"transports.sse.enabled",
"analysis.semanticAnalysis.llmIntegration.enabled",
];
return restartRequired.includes(key);
}
/**
* Restore configuration from backup
*/
public async restoreConfig(args: {
backup_path?: string;
confirm?: boolean;
}): Promise<ToolResponse> {
if (!args.backup_path) {
return {
content: [
{
type: "text",
text:
`❌ **Backup Path Required**\n\n` +
`The \`backup_path\` parameter is required for config restore operations.\n\n` +
`**Usage**: \`{ "action": "config_restore", "backup_path": "/path/to/backup", "confirm": true }\`\n\n` +
`**Note**: Backup files are typically named like \`config.json.backup.1640995200000\``,
},
],
isError: true,
};
}
if (!args.confirm) {
return {
content: [
{
type: "text",
text:
`⚠️ **Configuration Restore Confirmation Required**\n\n` +
`**Backup Path**: \`${args.backup_path}\`\n` +
`**Impact**: This will overwrite the current configuration file\n` +
`**Data Loss Risk**: Current configuration will be lost unless backed up\n\n` +
`**To proceed**: Set \`confirm: true\` to execute the restore.\n\n` +
`**Alternative**: Use \`config\` operations to make individual changes instead of full restore.`,
},
],
};
}
// Check if SafeConfigWriter is available
if (!this.safeConfigWriter) {
return {
content: [
{
type: "text",
text:
`❌ **Configuration Restore Unavailable**\n\n` +
`Configuration restoration is not available (SafeConfigWriter not initialized).\n` +
`This may indicate a file system permission issue or invalid configuration path.\n\n` +
`**Backup Path**: \`${args.backup_path}\`\n\n` +
`**Manual Restore**: You may need to manually copy the backup file to replace the current config.`,
},
],
isError: true,
};
}
try {
// Create a backup of the current config before restoring
const fs = await import("fs");
const currentConfigPath = this.safeConfigWriter.getConfigPath();
const emergencyBackupPath = `${currentConfigPath}.emergency.backup.${Date.now()}`;
if (fs.existsSync(currentConfigPath)) {
await fs.promises.copyFile(currentConfigPath, emergencyBackupPath);
this.logger.info(
`Emergency backup created before restore: ${emergencyBackupPath}`
);
}
// Perform the restoration
const restoreResult = await this.safeConfigWriter.restoreFromBackup(
args.backup_path
);
if (!restoreResult.success) {
return {
content: [
{
type: "text",
text:
`❌ **Configuration Restore Failed**\n\n` +
`**Backup Path**: \`${args.backup_path}\`\n` +
`**Error**: ${
restoreResult.error || restoreResult.message
}\n\n` +
`**Status**: Original configuration unchanged\n` +
`${
fs.existsSync(emergencyBackupPath)
? `**Emergency Backup**: ${emergencyBackupPath}\n`
: ""
}` +
`**Action**: Verify the backup file exists and is readable.`,
},
],
isError: true,
};
}
// Success! Configuration has been restored
let response = `✅ **Configuration Restored Successfully**\n\n`;
response += `**Restored From**: \`${args.backup_path}\`\n`;
response += `**Emergency Backup**: \`${emergencyBackupPath}\`\n`;
response += `**Timestamp**: ${new Date().toISOString()}\n\n`;
response += `⚠️ **Server Restart Recommended**\n\n`;
response += `Configuration has been restored from backup. A server restart is recommended `;
response += `to ensure all systems are using the restored configuration.\n\n`;
response += `**To restart**: Use \`{ "action": "restart", "confirm": true }\`\n\n`;
response += `**Recovery Options**:\n`;
response += `- **Undo**: \`{ "action": "config_restore", "backup_path": "${emergencyBackupPath}", "confirm": true }\`\n`;
response += `- **Check config**: \`{ "action": "config", "config": { "operation": "list" } }\``;
return this.createMinimalSystemResponse(response, "config_restore");
} catch (error) {
this.logger.error(
`Unexpected error during config restore from ${args.backup_path}:`,
error
);
return {
content: [
{
type: "text",
text:
`❌ **Unexpected Restore Error**\n\n` +
`**Backup Path**: \`${args.backup_path}\`\n` +
`**Error**: ${String(error)}\n\n` +
`**Status**: Configuration unchanged. System remains stable.\n` +
`**Action**: Check file permissions and backup file validity.`,
},
],
isError: true,
};
}
}
/**
* Restart server with confirmation and reason
*/
public async restartServer(args: {
reason?: string;
confirm?: boolean;
}): Promise<ToolResponse> {
const {
reason = "Manual restart requested via system_control",
confirm = false,
} = args;
if (!this.onRestart) {
return {
content: [
{
type: "text",
text: "❌ **Restart Unavailable**: Server restart functionality not configured. This may indicate the server is running in a mode that doesn't support programmatic restart.",
},
],
isError: true,
};
}
if (!confirm) {
return {
content: [
{
type: "text",
text:
`⚠️ **Server Restart Confirmation Required**\n\n` +
`**Reason**: ${reason}\n` +
`**Impact**: All active connections will be terminated\n` +
`**Downtime**: Server will restart (typically 5-10 seconds)\n\n` +
`**To proceed**: Set 'confirm: true' to execute the restart.\n\n` +
`🔄 **Alternative**: Use hot-reload via prompt_manager 'reload' action for most changes.`,
},
],
};
}
let response = `🚨 **Server Restart Initiated**\n\n`;
response += `**Reason**: ${reason}\n`;
response += `**Timestamp**: ${new Date().toISOString()}\n\n`;
response += `📊 **Pre-Restart System Status**:\n`;
response += `- **Uptime**: ${this.formatUptime(
this.systemControl.systemAnalytics.uptime
)}\n`;
response += `- **Total Executions**: ${this.systemControl.systemAnalytics.totalExecutions}\n`;
response += `- **Success Rate**: ${this.getSuccessRate()}%\n`;
if (this.systemControl.frameworkStateManager) {
const currentState =
this.systemControl.frameworkStateManager.getCurrentState();
response += `- **Active Framework**: ${currentState.activeFramework}\n`;
}
response += `\n⚡ **Server will restart in 2 seconds**... Please wait for reconnection.\n\n`;
response += `✅ All system state and configurations will be preserved.`;
// Schedule restart after response is sent
setTimeout(() => {
this.logger.info(
`System restart initiated via system_control. Reason: ${reason}`
);
this.onRestart!(reason);
}, 2000);
return this.createMinimalSystemResponse(response, "restart");
}
// Helper methods
private resetAnalyticsData(): void {
this.systemControl.systemAnalytics = {
totalExecutions: 0,
successfulExecutions: 0,
failedExecutions: 0,
averageExecutionTime: 0,
gateValidationCount: 0,
uptime: Date.now() - this.startTime,
performanceTrends: [],
};
}
/**
* Enable framework system
*/
public async enableFrameworkSystem(args: {
reason?: string;
}): Promise<ToolResponse> {
try {
if (!this.systemControl.frameworkStateManager) {
return createStructuredResponse(
"❌ Framework State Manager not available",
{
operation: "enable_framework",
error: "framework_manager_unavailable",
},
true
);
}
const reason = args.reason || "Manual enable via MCP tool";
this.systemControl.frameworkStateManager.enableFrameworkSystem(reason);
const status =
this.systemControl.frameworkStateManager.isFrameworkSystemEnabled();
let response = "✅ **Framework System Enabled**\n\n";
response += `**Status**: ${status ? "Enabled" : "Disabled"}\n`;
response += `**Reason**: ${reason}\n`;
response += `**Active Framework**: ${
this.systemControl.frameworkStateManager.getActiveFramework().name
}\n`;
response += `**Timestamp**: ${new Date().toISOString()}\n\n`;
response +=
"Framework injection will now be active for template and chain executions.\n\n";
response +=
"🔄 **Note**: Tool descriptions now reflect framework-enabled capabilities. Tool descriptions will show framework-enhanced functionality on next client connection/restart.";
return this.createMinimalSystemResponse(response, "enable_framework");
} catch (error) {
return this.handleError(error, "enable_framework_system");
}
}
/**
* Disable framework system
*/
public async disableFrameworkSystem(args: {
reason?: string;
}): Promise<ToolResponse> {
try {
if (!this.systemControl.frameworkStateManager) {
return createStructuredResponse(
"❌ Framework State Manager not available",
{
operation: "disable_framework",
error: "framework_manager_unavailable",
},
true
);
}
const reason = args.reason || "Manual disable via MCP tool";
this.systemControl.frameworkStateManager.disableFrameworkSystem(reason);
const status =
this.systemControl.frameworkStateManager.isFrameworkSystemEnabled();
let response = "🚫 **Framework System Disabled**\n\n";
response += `**Status**: ${status ? "Enabled" : "Disabled"}\n`;
response += `**Reason**: ${reason}\n`;
response += `**Timestamp**: ${new Date().toISOString()}\n\n`;
response +=
"Framework injection is now bypassed. All executions will use standard prompts without methodology enhancements.\n\n";
response +=
"🔄 **Note**: Tool descriptions now reflect framework-disabled state. Tool descriptions will show basic functionality (no framework enhancement) on next client connection/restart.";
return this.createMinimalSystemResponse(response, "disable_framework");
} catch (error) {
return this.handleError(error, "disable_framework_system");
}
}
/**
* Get framework system status
*/
public async getFrameworkSystemStatus(args: any): Promise<ToolResponse> {
try {
if (!this.systemControl.frameworkStateManager) {
return createStructuredResponse(
"❌ Framework State Manager not available",
{
operation: "framework_status",
error: "framework_manager_unavailable",
},
true
);
}
const state = this.systemControl.frameworkStateManager.getCurrentState();
const health = this.systemControl.frameworkStateManager.getSystemHealth();
let response = "📊 **Framework System Status**\n\n";
// Main status with enhanced clarity
const isEnabled = state.frameworkSystemEnabled;
const injectionStatus = isEnabled ? "✅ Active" : "🚫 Inactive";
response += `**System Status**: ${
state.frameworkSystemEnabled ? "✅ Enabled" : "🚫 Disabled"
}\n`;
response += `**Selected Framework**: ${state.activeFramework}\n`;
response += `**Framework Injection**: ${injectionStatus}\n`;
response += `**Health Status**: ${this.getHealthEmoji(
health.status
)} ${health.status.toUpperCase()}\n`;
response += `**Last Updated**: ${state.switchedAt.toISOString()}\n`;
response += `**Last Reason**: ${state.switchReason}\n\n`;
// Available frameworks
response += `**Available Frameworks**: ${health.availableFrameworks.join(
", "
)}\n\n`;
// Framework capabilities
if (state.frameworkSystemEnabled) {
response += "**Current Capabilities**:\n";
response += "• Framework-aware prompt injection\n";
response += "• Methodology-specific system prompts\n";
response += "• Quality gate validation\n";
response += "• Enhanced execution context\n\n";
} else {
response +=
"**Current Mode**: Standard execution (no framework enhancements)\n\n";
}
// Switching metrics
response += "**Switching Metrics**:\n";
response += `• Total Operations: ${state.switchingMetrics.switchCount}\n`;
response += `• Error Count: ${state.switchingMetrics.errorCount}\n`;
response += `• Avg Response Time: ${state.switchingMetrics.averageResponseTime.toFixed(
1
)}ms\n`;
// Health issues
if (health.issues.length > 0) {
response += "\n**Issues**:\n";
health.issues.forEach((issue) => {
response += `• ⚠️ ${issue}\n`;
});
}
return this.createMinimalSystemResponse(response, "framework_status");
} catch (error) {
return this.handleError(error, "framework_system_status");
}
}
/**
* Get health status emoji
*/
private getHealthEmoji(status: string): string {
switch (status) {
case "healthy":
return "✅";
case "degraded":
return "⚠️";
case "error":
return "❌";
default:
return "❓";
}
}
/**
* Error handling helper
*/
public handleError(error: unknown, context: string): ToolResponse {
utilsHandleError(error, context, this.logger);
return this.responseFormatter.formatErrorResponse(
error instanceof Error ? error : String(error),
{
tool: "system_control",
operation: context,
},
{
includeStructuredData: true,
}
);
}
}
/**
* Create consolidated system control
*/
export function createConsolidatedSystemControl(
logger: Logger,
mcpServer: any,
onRestart?: (reason: string) => Promise<void>
): ConsolidatedSystemControl {
return new ConsolidatedSystemControl(logger, mcpServer, onRestart);
}
```