This is page 5 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/config/tool-descriptions.json:
--------------------------------------------------------------------------------
```json
{
"version": "1.1.0",
"lastUpdated": "2025-01-14T00:00:00Z",
"tools": {
"prompt_engine": {
"description": "\ud83d\ude80 PROMPT ENGINE: Executes prompts with optional quality validation.\n\n\ud83d\udccb QUALITY GATE SYSTEM:\nQuality gates validate output before returning results. Use 'quality_gates' to apply validation rules, or 'custom_checks' for ad-hoc criteria.\n\n**Discover available gates**: Use `system_control({ action: 'gates', operation: 'list' })` to see all configured gates.\n\nGate modes:\n\u2022 enforce (default): Validates output, retries on failure with improvement hints (max 2 retries)\n\u2022 advise: Provides quality guidance without blocking\n\u2022 report: Validates and includes pass/fail status in response\n\nExample usage:\n{\n \"command\": \">>code_review code='...'\",\n \"quality_gates\": [\"gate-name-1\", \"gate-name-2\"],\n \"gate_mode\": \"enforce\"\n}",
"shortDescription": "\ud83d\udd25 DYNAMICALLY UPDATED: Process prompt templates and return executable instructions",
"category": "execution",
"parameters": {
"command": "Prompt name and arguments to process. WARNING: Will return instructions for YOU to execute, not just information. SIMPLE: >>prompt_name arguments (case-insensitive, hyphens converted to underscores). MULTI-LINE / RICH FORMATTING: {\"command\": \">>prompt_name\", \"args\": {\"content\": \"...\", \"execution_mode\": \"template\"}} keeps payload intact. ADVANCED: JSON with execution options",
"execution_mode": "Override intelligent auto-detection (default: auto)",
"gate_validation": "Quality gate validation (MANDATORY for chains, auto-detected by default, see metadata sections for gate details)",
"quality_gates": {
"type": "array",
"description": "Array of quality gate names to apply. Discover available gates using system_control with action='gates', operation='list'. Gates validate output quality and provide improvement guidance."
},
"custom_checks": {
"type": "array",
"description": "Array of custom quality checks (each with 'name' and 'description'). Creates simple validation gates based on your criteria. Example: [{name: 'production-ready', description: 'Include error handling'}]"
},
"gate_mode": {
"type": "string",
"enum": [
"enforce",
"advise",
"report"
],
"description": "How to apply quality gates: 'enforce' (block on failure, retry with hints), 'advise' (guidance only), 'report' (validate and report). Default: 'enforce' when quality_gates specified."
},
"step_confirmation": "Require confirmation between chain steps",
"llm_driven_execution": "Enable LLM-driven chain step coordination (requires semantic LLM integration)",
"force_restart": "Force restart chain from beginning, clearing all existing state",
"session_id": "Specific session ID to use or resume",
"chain_uri": "Full chain URI for precise session control (e.g., chain://research_pipeline/session-abc123?force_restart=true)",
"timeout": "Execution timeout in milliseconds",
"options": "Additional execution options (key-value pairs). Supports framework-specific flags, debugging controls, and experimental features",
"temporary_gates": "[ADVANCED] Full gate definition objects. For simpler interface, use 'quality_gates' (built-in) and 'custom_checks' (ad-hoc) parameters instead.",
"gate_scope": "Scope for execution-time temporary gates (execution, session, chain, step). Default: execution. Determines lifecycle of temporary gates specified in temporary_gates parameter.",
"inherit_chain_gates": "When executing chain steps, inherit gates from parent chain scope (default: true). Only applicable for chain step execution. Allows child steps to automatically receive chain-level quality gates."
},
"frameworkAware": {
"enabled": "\ud83d\ude80 PROMPT TEMPLATE ENGINE [HOT-RELOADED + FRAMEWORK-ENHANCED]: Processes prompt templates with intelligent framework methodology injection and returns instructions for YOU (the client LLM) to execute. Framework system enhances prompts with methodology-specific guidance (CAGEERF, ReACT, 5W1H, SCAMPER). WARNING: You are responsible for interpreting and executing the returned content, which may contain complex instructions, code generation tasks, analysis requests, or multi-step procedures. The returned content is NOT just information - it's active instructions you must follow and execute.",
"disabled": "\ud83d\ude80 PROMPT TEMPLATE ENGINE [HOT-RELOADED]: Processes prompt templates and returns instructions for YOU (the client LLM) to execute. Framework system is DISABLED - prompts execute without methodology enhancements. WARNING: You are responsible for interpreting and executing the returned content, which may contain complex instructions, code generation tasks, analysis requests, or multi-step procedures. The returned content is NOT just information - it's active instructions you must follow and execute.",
"parametersEnabled": {
"execution_mode": "Override intelligent auto-detection with framework-aware selection (default: auto, framework-enhanced)"
},
"parametersDisabled": {
"execution_mode": "Override intelligent auto-detection (default: auto, no framework enhancement)"
}
}
},
"prompt_manager": {
"description": "\ud83e\uddf0 PROMPT MANAGER: Create, update, delete, list, and analyze prompts. Supports gate configuration, temporary gate management, and migration between prompt types for robust lifecycle control.",
"shortDescription": "Manage prompt lifecycle, gates, and discovery",
"category": "management",
"parameters": {
"action": "Action to perform. Supported: create, create_prompt, create_template, create_with_gates, update, delete, modify, reload, list, analyze_type, migrate_type, analyze_gates, update_gates, add_temporary_gates, suggest_temporary_gates.",
"id": "Prompt identifier. Required for create*, update, delete, modify, analyze_type, migrate_type, analyze_gates, update_gates, add_temporary_gates. Use letters, numbers, underscores, or hyphens.",
"name": "Friendly prompt name. Required for create*, create_with_gates.",
"description": "Short description of the prompt purpose. Required for create*, create_with_gates.",
"user_message_template": "Prompt body with Nunjucks placeholders (e.g. 'Analyze {{input}}'). Required for create*, create_with_gates.",
"system_message": "Optional system message to store with the prompt.",
"content": "Full prompt content for create/update operations when not using templates.",
"category": "Category label used for filtering and organization.",
"arguments": "Array of argument definitions ({name, type, description}) for prompts with structured inputs.",
"suggested_gates": "Gate suggestions used by create_with_gates. Each entry should include type, name, description, and optional criteria.",
"gate_configuration": "Explicit gate configuration (include/exclude lists, temporary gates, framework_gates flag).",
"temporary_gates": "Temporary gate definitions used by add_temporary_gates (include name, type, scope, description, guidance, pass_criteria).",
"gate_scope": "Scope for temporary gates (execution, session, chain, step).",
"inherit_chain_gates": "When true, inherit gates from the parent chain (default true for add_temporary_gates).",
"search_query": "Search expression for list (e.g. 'category:code type:chain').",
"force": "Bypass confirmation prompts for supported actions."
},
"frameworkAware": {
"enabled": "\ud83e\uddf0 PROMPT MANAGER [FRAMEWORK-ENABLED]: Same functionality with framework-aware metadata exposed. Use when methodology switching is active.",
"disabled": "\ud83e\uddf0 PROMPT MANAGER [FRAMEWORK-DISABLED]: Operates without applying methodology metadata or guidance.",
"parametersEnabled": {
"action": "Same as base mode; framework context is available for downstream processing"
},
"parametersDisabled": {
"action": "Same as base mode"
}
}
},
"system_control": {
"description": "\u2699\ufe0f SYSTEM CONTROL: Framework management, gate discovery, analytics, and system operations.\n\n**Discover quality gates**: Use `action='gates', operation='list'` to see all available validation gates.\n**Discover frameworks**: Use `action='framework', operation='list'` to see available methodologies.",
"shortDescription": "Manage framework state, metrics, and maintenance",
"category": "system",
"parameters": {
"action": "Top-level command. Supported values: status, framework, gates, analytics, config, maintenance.",
"operation": "Sub-command for the selected action (e.g. framework: switch|list|enable|disable, analytics: view|reset|history).",
"framework": "Framework identifier when switching (CAGEERF, ReACT, 5W1H, SCAMPER).",
"config_path": "Configuration path or key for config operations.",
"config_value": "Value to write when performing config updates.",
"reason": "Audit-friendly explanation for switches, config changes, or restarts.",
"restart_reason": "Specific reason recorded for maintenance/restart operations.",
"confirm": "Set true to acknowledge confirmation-required operations (e.g. reset, restore, restart).",
"include_history": "Include historical entries (where supported).",
"include_metrics": "Include detailed metrics output (where supported).",
"show_details": "Request an expanded response for list/status style commands."
},
"frameworkAware": {
"enabled": "\u2699\ufe0f SYSTEM CONTROL [FRAMEWORK-ENABLED]: Framework switching and gate orchestration available.",
"disabled": "\u2699\ufe0f SYSTEM CONTROL [FRAMEWORK-DISABLED]: Limited to status, analytics, config, and maintenance.",
"parametersEnabled": {
"action": "Same as base mode; framework operations succeed"
},
"parametersDisabled": {
"action": "Same as base mode; framework operations return informative errors"
}
}
}
}
}
```
--------------------------------------------------------------------------------
/server/src/gates/gate-state-manager.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Gate System Manager - Runtime State Management
*
* Provides runtime enable/disable functionality for the gates system,
* following the same pattern as FrameworkStateManager for consistency.
*/
import { EventEmitter } from 'events';
import path from 'path';
import fs from 'fs/promises';
import { Logger } from '../logging/index.js';
/**
* Gate system state interface
*/
export interface GateSystemState {
enabled: boolean;
enabledAt: Date;
enableReason: string;
isHealthy: boolean;
validationMetrics: {
totalValidations: number;
successfulValidations: number;
averageValidationTime: number;
lastValidationTime: Date | null;
};
}
/**
* Gate system health status
*/
export interface GateSystemHealth {
status: "healthy" | "degraded" | "disabled";
enabled: boolean;
totalValidations: number;
successRate: number;
averageValidationTime: number;
lastValidationTime: Date | null;
issues: string[];
}
/**
* Gate system enable/disable request
*/
export interface GateSystemToggleRequest {
enabled: boolean;
reason?: string;
}
/**
* Gate system events
*/
export interface GateSystemEvents {
'system-enabled': [reason: string];
'system-disabled': [reason: string];
'health-changed': [health: GateSystemHealth];
'validation-completed': [success: boolean, executionTime: number];
}
/**
* Gate System Manager - Runtime state management
*/
export class GateSystemManager extends EventEmitter {
private currentState: GateSystemState;
private logger: Logger;
private stateFilePath: string;
private healthCheckInterval?: NodeJS.Timeout;
constructor(logger: Logger, stateDirectory?: string) {
super();
this.logger = logger;
// Default state - gates enabled by default
this.currentState = {
enabled: true,
enabledAt: new Date(),
enableReason: 'System initialization (default enabled)',
isHealthy: true,
validationMetrics: {
totalValidations: 0,
successfulValidations: 0,
averageValidationTime: 0,
lastValidationTime: null
}
};
// Set up state file path
const baseDir = stateDirectory || path.join(process.cwd(), 'runtime-state');
this.stateFilePath = path.join(baseDir, 'gate-system-state.json');
this.logger.debug(`GateSystemManager initialized with state file: ${this.stateFilePath}`);
}
/**
* Initialize the gate system manager
*/
async initialize(): Promise<void> {
try {
// Load persisted state if available
await this.loadStateFromFile();
// Start health monitoring
this.startHealthMonitoring();
this.logger.info(`🚪 Gate System Manager initialized - System ${this.currentState.enabled ? 'enabled' : 'disabled'}`);
} catch (error) {
this.logger.error('Failed to initialize GateSystemManager:', error);
throw error;
}
}
/**
* Load state from persistent storage
*/
private async loadStateFromFile(): Promise<void> {
try {
// Ensure state directory exists
await fs.mkdir(path.dirname(this.stateFilePath), { recursive: true });
// Try to load existing state
const stateData = await fs.readFile(this.stateFilePath, 'utf-8');
const persistedState = JSON.parse(stateData);
// Validate and restore state
if (this.isValidPersistedState(persistedState)) {
this.currentState.enabled = persistedState.enabled;
this.currentState.enabledAt = new Date(persistedState.enabledAt);
this.currentState.enableReason = persistedState.enableReason;
this.currentState.validationMetrics = {
...this.currentState.validationMetrics,
...persistedState.validationMetrics,
lastValidationTime: persistedState.validationMetrics.lastValidationTime
? new Date(persistedState.validationMetrics.lastValidationTime)
: null
};
this.logger.info(`✅ Loaded persisted gate system state: ${persistedState.enabled ? 'enabled' : 'disabled'}`);
} else {
this.logger.warn('⚠️ Invalid persisted gate state format, using defaults');
await this.saveStateToFile(); // Save valid defaults
}
} catch (error) {
if ((error as any).code === 'ENOENT') {
// No state file exists yet - use defaults and create initial state
this.logger.info('📁 No existing gate system state found, using defaults');
await this.saveStateToFile();
} else {
this.logger.error('Failed to load gate system state:', error);
// Continue with defaults but don't fail initialization
}
}
}
/**
* Save current state to persistent storage
*/
private async saveStateToFile(): Promise<void> {
try {
const stateToSave = {
enabled: this.currentState.enabled,
enabledAt: this.currentState.enabledAt.toISOString(),
enableReason: this.currentState.enableReason,
validationMetrics: {
...this.currentState.validationMetrics,
lastValidationTime: this.currentState.validationMetrics.lastValidationTime?.toISOString() || null
},
savedAt: new Date().toISOString()
};
await fs.writeFile(this.stateFilePath, JSON.stringify(stateToSave, null, 2));
this.logger.debug('Gate system state saved to file');
} catch (error) {
this.logger.error('Failed to save gate system state:', error);
// Don't throw - this shouldn't break the system
}
}
/**
* Validate persisted state structure
*/
private isValidPersistedState(state: any): boolean {
return (
state &&
typeof state.enabled === 'boolean' &&
typeof state.enabledAt === 'string' &&
typeof state.enableReason === 'string' &&
state.validationMetrics &&
typeof state.validationMetrics.totalValidations === 'number'
);
}
/**
* Check if gate system is enabled
*/
isGateSystemEnabled(): boolean {
return this.currentState.enabled;
}
/**
* Enable the gate system
*/
async enableGateSystem(reason: string = 'User request'): Promise<void> {
if (this.currentState.enabled) {
this.logger.debug('Gate system already enabled');
return;
}
this.currentState.enabled = true;
this.currentState.enabledAt = new Date();
this.currentState.enableReason = reason;
this.currentState.isHealthy = true;
// Save state to file
await this.saveStateToFile();
// Emit events
this.emit('system-enabled', reason);
this.emit('health-changed', this.getSystemHealth());
this.logger.info(`🟢 Gate System enabled: ${reason}`);
}
/**
* Disable the gate system
*/
async disableGateSystem(reason: string = 'User request'): Promise<void> {
if (!this.currentState.enabled) {
this.logger.debug('Gate system already disabled');
return;
}
this.currentState.enabled = false;
this.currentState.enableReason = `Disabled: ${reason}`;
// Save state to file
await this.saveStateToFile();
// Emit events
this.emit('system-disabled', reason);
this.emit('health-changed', this.getSystemHealth());
this.logger.info(`🔴 Gate System disabled: ${reason}`);
}
/**
* Get current system health
*/
getSystemHealth(): GateSystemHealth {
const metrics = this.currentState.validationMetrics;
const successRate = metrics.totalValidations > 0
? (metrics.successfulValidations / metrics.totalValidations) * 100
: 100;
let status: "healthy" | "degraded" | "disabled" = "healthy";
const issues: string[] = [];
if (!this.currentState.enabled) {
status = "disabled";
} else if (successRate < 80 && metrics.totalValidations > 10) {
status = "degraded";
issues.push("Low validation success rate");
} else if (metrics.averageValidationTime > 1000) {
status = "degraded";
issues.push("High validation latency");
}
return {
status,
enabled: this.currentState.enabled,
totalValidations: metrics.totalValidations,
successRate: Math.round(successRate * 100) / 100,
averageValidationTime: Math.round(metrics.averageValidationTime * 100) / 100,
lastValidationTime: metrics.lastValidationTime,
issues
};
}
/**
* Record a validation execution for metrics
*/
recordValidation(success: boolean, executionTime: number): void {
const metrics = this.currentState.validationMetrics;
metrics.totalValidations++;
if (success) {
metrics.successfulValidations++;
}
// Update average execution time using running average
metrics.averageValidationTime =
(metrics.averageValidationTime * (metrics.totalValidations - 1) + executionTime) /
metrics.totalValidations;
metrics.lastValidationTime = new Date();
// Save state periodically (every 10 validations)
if (metrics.totalValidations % 10 === 0) {
this.saveStateToFile().catch(error => {
this.logger.error('Failed to save validation metrics:', error);
});
}
// Emit event
this.emit('validation-completed', success, executionTime);
this.logger.debug(`Validation recorded: ${success ? 'success' : 'failure'} (${executionTime}ms)`);
}
/**
* Get current state for inspection
*/
getCurrentState(): GateSystemState {
return { ...this.currentState };
}
/**
* Start health monitoring
*/
private startHealthMonitoring(): void {
// Check system health every 30 seconds
this.healthCheckInterval = setInterval(() => {
const health = this.getSystemHealth();
// Only emit health changes if status actually changed
const previousStatus = this.currentState.isHealthy;
const currentlyHealthy = health.status === 'healthy';
if (previousStatus !== currentlyHealthy) {
this.currentState.isHealthy = currentlyHealthy;
this.emit('health-changed', health);
if (!currentlyHealthy) {
this.logger.warn(`🚨 Gate system health degraded: ${health.issues.join(', ')}`);
}
}
}, 30000);
}
/**
* Cleanup resources
*/
async cleanup(): Promise<void> {
if (this.healthCheckInterval) {
clearInterval(this.healthCheckInterval);
}
// Final state save
await this.saveStateToFile();
this.logger.debug('GateSystemManager cleanup completed');
}
}
/**
* Create a gate system manager instance
*/
export function createGateSystemManager(
logger: Logger,
stateDirectory?: string
): GateSystemManager {
return new GateSystemManager(logger, stateDirectory);
}
```
--------------------------------------------------------------------------------
/server/tests/scripts/integration-routing-system.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Routing System Integration Tests
* Tests for the intelligent command routing functionality added to the prompt engine
*/
async function runRoutingSystemTests() {
try {
console.log('🧪 Running Routing System Integration tests...');
console.log('📋 Testing intelligent command routing and built-in command support');
// Import global resource tracker for process cleanup
const { globalResourceTracker } = await import('../../dist/utils/global-resource-tracker.js');
// Test the routing pattern detection directly (simulating the logic from prompt engine)
function testRoutingPatterns() {
const patterns = [
{ command: '>>listprompts', expected: 'prompt_manager', description: 'listprompts command routing' },
{ command: 'listprompts', expected: 'prompt_manager', description: 'listprompts without >> prefix' },
{ command: '>>listprompts category:analysis', expected: 'prompt_manager', description: 'listprompts with filter' },
{ command: '>>help', expected: 'system_control', description: 'help command routing' },
{ command: 'help', expected: 'system_control', description: 'help without >> prefix' },
{ command: '>>status', expected: 'system_control', description: 'status command routing' },
{ command: '>>analytics', expected: 'system_control', description: 'analytics command routing' },
{ command: '>>framework switch CAGEERF', expected: 'system_control', description: 'framework switch routing' },
{ command: '>>some_prompt_name', expected: null, description: 'regular prompt should not route' },
{ command: '/listprompts', expected: 'prompt_manager', description: 'listprompts with / prefix' },
{ command: '/help', expected: 'system_control', description: 'help with / prefix' },
];
console.log('🔍 Test 1: Routing Pattern Detection');
let passedPatterns = 0;
for (const test of patterns) {
const trimmedCommand = test.command.trim();
let matchedTool = null;
// Built-in commands that route to prompt_manager
if (/^(>>|\/)?listprompts?(\s.*)?$/i.test(trimmedCommand)) {
matchedTool = 'prompt_manager';
}
// Help and status commands that route to system_control
else if (/^(>>|\/)?help$/i.test(trimmedCommand)) {
matchedTool = 'system_control';
}
else if (/^(>>|\/)?status$/i.test(trimmedCommand)) {
matchedTool = 'system_control';
}
// Framework switch commands
else if (trimmedCommand.match(/^(>>|\/)?framework\s+(switch|change)\s+(.+)$/i)) {
matchedTool = 'system_control';
}
// Analytics/metrics commands
else if (/^(>>|\/)?analytics?$/i.test(trimmedCommand)) {
matchedTool = 'system_control';
}
const result = matchedTool === test.expected ? '✅' : '❌';
const status = matchedTool === test.expected ? 'PASSED' : 'FAILED';
console.log(`${result} ${test.description}: ${status}`);
if (matchedTool === test.expected) {
passedPatterns++;
} else {
console.log(` Expected: ${test.expected || 'none'}, Got: ${matchedTool || 'none'}`);
}
}
return passedPatterns === patterns.length;
}
// Test parameter translation logic
function testParameterTranslation() {
console.log('🔍 Test 2: Parameter Translation');
const testCases = [
{
command: '>>listprompts',
expected: { action: 'list' },
description: 'listprompts basic translation'
},
{
command: '>>listprompts category:analysis',
expected: { action: 'list', search_query: 'category:analysis' },
description: 'listprompts with filter translation'
},
{
command: '>>help',
expected: { action: 'status', show_details: true },
description: 'help command translation'
},
{
command: '>>status',
expected: { action: 'status' },
description: 'status command translation'
}
];
let passedTranslations = 0;
for (const test of testCases) {
const trimmedCommand = test.command.trim();
let translatedParams = null;
// Simulate the parameter translation logic
if (/^(>>|\/)?listprompts?(\s.*)?$/i.test(trimmedCommand)) {
const args = trimmedCommand.replace(/^(>>|\/)?listprompts?\s*/i, '').trim();
translatedParams = {
action: 'list',
...(args && { search_query: args })
};
} else if (/^(>>|\/)?help$/i.test(trimmedCommand)) {
translatedParams = {
action: 'status',
show_details: true
};
} else if (/^(>>|\/)?status$/i.test(trimmedCommand)) {
translatedParams = {
action: 'status'
};
}
// Simple comparison for testing
const paramsMatch = JSON.stringify(translatedParams) === JSON.stringify(test.expected);
const result = paramsMatch ? '✅' : '❌';
const status = paramsMatch ? 'PASSED' : 'FAILED';
console.log(`${result} ${test.description}: ${status}`);
if (paramsMatch) {
passedTranslations++;
} else {
console.log(` Expected: ${JSON.stringify(test.expected)}`);
console.log(` Got: ${JSON.stringify(translatedParams)}`);
}
}
return passedTranslations === testCases.length;
}
// Test built-in command recognition in parser
function testBuiltinCommandRecognition() {
console.log('🔍 Test 3: Built-in Command Recognition');
const builtinCommands = [
'listprompts', 'listprompt', 'list_prompts',
'help', 'commands',
'status', 'health',
'analytics', 'metrics'
];
// Simulate the isBuiltinCommand logic
function isBuiltinCommand(promptId) {
return builtinCommands.includes(promptId.toLowerCase());
}
let passedRecognition = 0;
const testCommands = [
{ command: 'listprompts', shouldRecognize: true },
{ command: 'help', shouldRecognize: true },
{ command: 'status', shouldRecognize: true },
{ command: 'analytics', shouldRecognize: true },
{ command: 'some_regular_prompt', shouldRecognize: false },
{ command: 'LISTPROMPTS', shouldRecognize: true }, // Case insensitive
{ command: 'unknown_command', shouldRecognize: false }
];
for (const test of testCommands) {
const recognized = isBuiltinCommand(test.command);
const result = recognized === test.shouldRecognize ? '✅' : '❌';
const status = recognized === test.shouldRecognize ? 'PASSED' : 'FAILED';
console.log(`${result} Command '${test.command}' recognition: ${status}`);
if (recognized === test.shouldRecognize) {
passedRecognition++;
}
}
return passedRecognition === testCommands.length;
}
// Test error message enhancements
function testErrorMessageEnhancements() {
console.log('🔍 Test 4: Enhanced Error Messages');
function getBuiltinCommandHint(promptId) {
const lower = promptId.toLowerCase();
if (lower.includes('list') && lower.includes('prompt')) {
return '\n\nDid you mean >>listprompts?';
}
if (lower === 'commands' || lower === 'help') {
return '\n\nTry >>help for available commands.';
}
if (lower === 'stat' || lower === 'status') {
return '\n\nTry >>status for system status.';
}
return '';
}
const testCases = [
{ command: 'listprompt', expectedHint: '\n\nDid you mean >>listprompts?' },
{ command: 'commands', expectedHint: '\n\nTry >>help for available commands.' },
{ command: 'stat', expectedHint: '\n\nTry >>status for system status.' },
{ command: 'unknown', expectedHint: '' }
];
let passedHints = 0;
for (const test of testCases) {
const hint = getBuiltinCommandHint(test.command);
const result = hint === test.expectedHint ? '✅' : '❌';
const status = hint === test.expectedHint ? 'PASSED' : 'FAILED';
console.log(`${result} Error hint for '${test.command}': ${status}`);
if (hint === test.expectedHint) {
passedHints++;
}
}
return passedHints === testCases.length;
}
// Run all tests
const results = [
testRoutingPatterns(),
testParameterTranslation(),
testBuiltinCommandRecognition(),
testErrorMessageEnhancements()
];
const passedTests = results.filter(r => r).length;
const totalTests = results.length;
console.log('\n📊 Routing System Integration Tests Summary:');
console.log(` ✅ Passed: ${passedTests}/${totalTests} test categories`);
console.log(` 📊 Success Rate: ${((passedTests/totalTests)*100).toFixed(1)}%`);
// Check for remaining resources before exit
console.log('\n🔍 Checking for remaining global resources...');
globalResourceTracker.logDiagnostics();
const cleared = globalResourceTracker.emergencyCleanup();
if (cleared > 0) {
console.log(`💀 Emergency cleanup cleared ${cleared} additional resources`);
}
if (passedTests === totalTests) {
console.log('🎉 All Routing System Integration tests passed!');
// Emergency process exit to prevent hanging due to global Node.js resources
console.log('💀 Forcing process exit to prevent hanging from global timers...');
setTimeout(() => process.exit(0), 100); // Small delay to ensure log output
return true;
} else {
console.error('❌ Some Routing System Integration tests failed');
// Emergency process exit for failure case as well
console.log('💀 Forcing process exit to prevent hanging from global timers...');
setTimeout(() => process.exit(1), 100); // Small delay to ensure log output
return false;
}
} catch (error) {
console.error('❌ Routing System Integration tests failed with error:', error.message);
if (error.stack) {
console.error('Stack trace:', error.stack);
}
// Emergency process exit for error case as well
console.log('💀 Forcing process exit due to test error to prevent hanging from global timers...');
setTimeout(() => process.exit(1), 100); // Small delay to ensure log output
return false;
}
}
// Run the tests
if (import.meta.url === `file://${process.argv[1]}`) {
runRoutingSystemTests().catch(error => {
console.error('❌ Test execution failed:', error);
process.exit(1);
});
}
export { runRoutingSystemTests };
```
--------------------------------------------------------------------------------
/server/src/semantic/integrations/llm-clients.ts:
--------------------------------------------------------------------------------
```typescript
/**
* LLM Integration Clients for Semantic Analysis
*
* Provides concrete implementations for different LLM providers
* to enable intelligent semantic analysis when configured.
*/
import { Logger } from "../../logging/index.js";
import { LLMIntegrationConfig, LLMProvider } from "../../types/index.js";
import { LLMClient } from "../configurable-semantic-analyzer.js";
/**
* Base LLM client with common functionality
*/
abstract class BaseLLMClient implements LLMClient {
protected logger: Logger;
protected config: LLMIntegrationConfig;
constructor(logger: Logger, config: LLMIntegrationConfig) {
this.logger = logger;
this.config = config;
}
abstract classify(request: {
text: string;
task: string;
categories: string[];
methodologies: string[];
}): Promise<{
executionType: string;
confidence: number;
reasoning: string[];
recommendedFramework?: string;
complexity: string;
}>;
/**
* Common prompt construction for semantic analysis
*/
protected buildAnalysisPrompt(request: {
text: string;
task: string;
categories: string[];
methodologies: string[];
}): string {
return `${request.task}
Prompt Text:
"""
${request.text}
"""
Available Execution Types: ${request.categories.join(', ')}
Available Methodologies: ${request.methodologies.join(', ')}
Please analyze this prompt and return:
1. executionType: One of [${request.categories.join(', ')}]
2. confidence: Number between 0 and 1
3. reasoning: Array of strings explaining your analysis
4. recommendedFramework: One of [${request.methodologies.join(', ')}] or "none"
5. complexity: One of ["low", "medium", "high"]
Respond in JSON format only.`;
}
/**
* Parse LLM response and validate format
*/
protected parseResponse(response: string): {
executionType: string;
confidence: number;
reasoning: string[];
recommendedFramework?: string;
complexity: string;
} {
try {
const parsed = JSON.parse(response);
return {
executionType: parsed.executionType || "template",
confidence: Math.max(0.1, Math.min(1.0, parsed.confidence || 0.5)),
reasoning: Array.isArray(parsed.reasoning) ? parsed.reasoning : ["LLM analysis performed"],
recommendedFramework: parsed.recommendedFramework === "none" ? undefined : parsed.recommendedFramework,
complexity: ["low", "medium", "high"].includes(parsed.complexity) ? parsed.complexity : "medium"
};
} catch (error) {
this.logger.warn("Failed to parse LLM response, using defaults:", error);
return {
executionType: "template",
confidence: 0.3,
reasoning: ["Failed to parse LLM response"],
complexity: "medium"
};
}
}
}
/**
* OpenAI client implementation
*/
export class OpenAIClient extends BaseLLMClient {
async classify(request: {
text: string;
task: string;
categories: string[];
methodologies: string[];
}): Promise<{
executionType: string;
confidence: number;
reasoning: string[];
recommendedFramework?: string;
complexity: string;
}> {
if (!this.config.apiKey) {
throw new Error("OpenAI API key not configured");
}
const prompt = this.buildAnalysisPrompt(request);
try {
const response = await fetch(this.config.endpoint || "https://api.openai.com/v1/chat/completions", {
method: "POST",
headers: {
"Authorization": `Bearer ${this.config.apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: this.config.model,
messages: [
{
role: "system",
content: "You are an expert at analyzing prompts for execution strategy and framework requirements. Always respond with valid JSON."
},
{
role: "user",
content: prompt
}
],
max_tokens: this.config.maxTokens,
temperature: this.config.temperature
})
});
if (!response.ok) {
throw new Error(`OpenAI API error: ${response.status} ${response.statusText}`);
}
const data = await response.json() as any;
const content = data.choices?.[0]?.message?.content;
if (!content) {
throw new Error("No content in OpenAI response");
}
this.logger.debug("OpenAI analysis completed successfully");
return this.parseResponse(content);
} catch (error) {
this.logger.error("OpenAI API call failed:", error);
throw error;
}
}
}
/**
* Anthropic client implementation
*/
export class AnthropicClient extends BaseLLMClient {
async classify(request: {
text: string;
task: string;
categories: string[];
methodologies: string[];
}): Promise<{
executionType: string;
confidence: number;
reasoning: string[];
recommendedFramework?: string;
complexity: string;
}> {
if (!this.config.apiKey) {
throw new Error("Anthropic API key not configured");
}
const prompt = this.buildAnalysisPrompt(request);
try {
const response = await fetch(this.config.endpoint || "https://api.anthropic.com/v1/messages", {
method: "POST",
headers: {
"Authorization": `Bearer ${this.config.apiKey}`,
"Content-Type": "application/json",
"anthropic-version": "2023-06-01"
},
body: JSON.stringify({
model: this.config.model || "claude-3-haiku-20240307",
max_tokens: this.config.maxTokens,
temperature: this.config.temperature,
messages: [
{
role: "user",
content: prompt
}
]
})
});
if (!response.ok) {
throw new Error(`Anthropic API error: ${response.status} ${response.statusText}`);
}
const data = await response.json() as any;
const content = data.content?.[0]?.text;
if (!content) {
throw new Error("No content in Anthropic response");
}
this.logger.debug("Anthropic analysis completed successfully");
return this.parseResponse(content);
} catch (error) {
this.logger.error("Anthropic API call failed:", error);
throw error;
}
}
}
/**
* Custom endpoint client implementation
*/
export class CustomClient extends BaseLLMClient {
async classify(request: {
text: string;
task: string;
categories: string[];
methodologies: string[];
}): Promise<{
executionType: string;
confidence: number;
reasoning: string[];
recommendedFramework?: string;
complexity: string;
}> {
if (!this.config.endpoint) {
throw new Error("Custom endpoint not configured");
}
const prompt = this.buildAnalysisPrompt(request);
try {
const headers: Record<string, string> = {
"Content-Type": "application/json"
};
if (this.config.apiKey) {
headers["Authorization"] = `Bearer ${this.config.apiKey}`;
}
const response = await fetch(this.config.endpoint, {
method: "POST",
headers,
body: JSON.stringify({
model: this.config.model,
prompt: prompt,
max_tokens: this.config.maxTokens,
temperature: this.config.temperature
})
});
if (!response.ok) {
throw new Error(`Custom endpoint error: ${response.status} ${response.statusText}`);
}
const data = await response.json() as any;
// Assume the custom endpoint returns the analysis directly
const content = data.response || data.content || data.text;
if (!content) {
throw new Error("No content in custom endpoint response");
}
this.logger.debug("Custom endpoint analysis completed successfully");
return this.parseResponse(content);
} catch (error) {
this.logger.error("Custom endpoint call failed:", error);
throw error;
}
}
}
/**
* Detect LLM provider from endpoint URL
*/
function detectProviderFromEndpoint(endpoint: string | null): LLMProvider {
if (!endpoint) {
throw new Error("Endpoint URL is required for provider auto-detection");
}
const url = endpoint.toLowerCase();
if (url.includes("api.openai.com")) {
return "openai";
} else if (url.includes("api.anthropic.com")) {
return "anthropic";
} else {
return "custom";
}
}
/**
* LLM client factory
*/
export class LLMClientFactory {
static create(logger: Logger, config: LLMIntegrationConfig): LLMClient {
try {
const provider = detectProviderFromEndpoint(config.endpoint);
switch (provider) {
case "openai":
return new OpenAIClient(logger, config);
case "anthropic":
return new AnthropicClient(logger, config);
case "custom":
return new CustomClient(logger, config);
default:
throw new Error(`Unsupported LLM provider: ${provider}`);
}
} catch (error) {
throw new Error(
`Failed to create LLM client: ${error instanceof Error ? error.message : 'Unknown error'}. ` +
`Please ensure the endpoint URL is valid and follows the format: ` +
`"https://api.openai.com/v1/chat/completions" for OpenAI, ` +
`"https://api.anthropic.com/v1/messages" for Anthropic, ` +
`or a custom endpoint URL for other providers.`
);
}
}
/**
* Test LLM client configuration
*/
static async testClient(logger: Logger, config: LLMIntegrationConfig): Promise<boolean> {
try {
// Auto-detect provider before testing
const provider = detectProviderFromEndpoint(config.endpoint);
logger.debug(`Auto-detected LLM provider: ${provider} from endpoint: ${config.endpoint}`);
const client = LLMClientFactory.create(logger, config);
const testResult = await client.classify({
text: "Analyze this simple test prompt with two arguments: {{input}} and {{context}}",
task: "Test classification",
categories: ["prompt", "template"],
methodologies: ["CAGEERF", "none"]
});
// Basic validation that we got a valid response
return Boolean(testResult.executionType &&
testResult.confidence > 0 &&
testResult.reasoning.length > 0);
} catch (error) {
logger.error("LLM client test failed:", error);
return false;
}
}
}
/**
* Environment variable configuration helper
* Provider is auto-detected from endpoint URL
*/
export function loadLLMConfigFromEnv(): Partial<LLMIntegrationConfig> {
return {
enabled: process.env.MCP_LLM_ENABLED === "true",
apiKey: process.env.MCP_LLM_API_KEY || null,
endpoint: process.env.MCP_LLM_ENDPOINT || null,
model: process.env.MCP_LLM_MODEL || "gpt-4",
maxTokens: parseInt(process.env.MCP_LLM_MAX_TOKENS || "1000"),
temperature: parseFloat(process.env.MCP_LLM_TEMPERATURE || "0.1")
};
}
```
--------------------------------------------------------------------------------
/docs/chain-modification-examples.md:
--------------------------------------------------------------------------------
```markdown
# Chain Modification Workflow Examples
This document provides practical examples of the **correct way** to modify chains using the MCP tools, based on real scenarios.
## Example 1: Adding Vault Search to Notes Chain
### The Request
> "Currently our note does not actually pull from relevant related notes in our vault, it just makes some up. Find the relevant step in our prompt chain, and refine it so it does look for, and valuable relevant notes in our vault"
### ❌ Wrong Approach (from logFail.txt)
The agent incorrectly tried to:
1. Use `Update()` to modify chain.json files directly
2. Use `Write()` to create new step files
3. Bypass the MCP tool system entirely
### ✅ Correct Approach
#### Step 1: Analyze Current Chain
```bash
# List all notes-related prompts
prompt_manager(action: "list", filter: "notes")
# Get details about the notes chain
prompt_manager(action: "list", filter: "type:chain notes", verbose: true)
```
#### Step 2: Check for Vault-Related Components
```bash
# Search for existing vault functionality
prompt_manager(action: "list", filter: "vault")
# Search for related notes functionality
prompt_manager(action: "list", filter: "related notes")
```
#### Step 3: Create Missing Components (if needed)
```bash
# If vault_related_notes_finder doesn't exist, create it
prompt_manager(action: "create",
id: "vault_related_notes_finder",
name: "Vault Related Notes Finder",
category: "content_processing",
description: "Searches vault for actual related notes using content analysis",
system_message: "You are an expert at finding related notes in a knowledge vault. Search for notes that are thematically and conceptually related to the given content.",
user_message_template: "Search in vault path: {{vault_path}}\n\nFind notes related to this topic: {{note_topic}}\n\nContent areas to analyze:\n{{content_areas}}\n\nReturn actual related notes from the vault, not fictional ones.",
arguments: [
{"name": "vault_path", "description": "Path to the vault directory", "required": true},
{"name": "note_topic", "description": "Main topic/content to find related notes for", "required": true},
{"name": "content_areas", "description": "Specific content areas to analyze", "required": false}
])
```
#### Step 4: Update the Chain Structure
```bash
# Update the notes_modular chain to include vault search step
prompt_manager(action: "update",
id: "notes_modular",
description: "Enhanced analysis chain: processes content through initial analysis, deep analysis, structured markdown creation, vault-based related notes discovery, and final refinement with actual cross-references.",
chain_steps: [
{
"id": "step_1",
"name": "Initial Content Analysis (Step 1 of 5)",
"description": "Initial analysis of provided content",
"promptId": "content_analysis",
"order": 0,
"dependencies": [],
"inputMapping": {
"content": "content"
},
"outputMapping": {
"result": "content_analysis_output"
}
},
{
"id": "step_2",
"name": "Deep Analysis (Step 2 of 5)",
"description": "Deep analysis building on initial analysis",
"promptId": "deep_analysis",
"order": 1,
"dependencies": ["step_1"],
"inputMapping": {
"content": "content",
"initial_analysis": "content_analysis_output"
},
"outputMapping": {
"result": "deep_analysis_output"
}
},
{
"id": "step_3",
"name": "Markdown Notebook Creation (Step 3 of 5)",
"description": "Convert analysis into structured markdown notebook",
"promptId": "markdown_notebook",
"order": 2,
"dependencies": ["step_2"],
"inputMapping": {
"content": "content",
"analysis": "deep_analysis_output"
},
"outputMapping": {
"result": "notebook_output"
}
},
{
"id": "step_4",
"name": "Vault Related Notes Search (Step 4 of 5)",
"description": "Search vault for actual related notes using content analysis",
"promptId": "vault_related_notes_finder",
"order": 3,
"dependencies": ["step_3"],
"inputMapping": {
"note_topic": "content",
"content_areas": "deep_analysis_output",
"vault_path": "/mnt/c/Users/legoj/Notes/Notion"
},
"outputMapping": {
"result": "related_notes"
},
"timeout": 300000,
"optional": false
},
{
"id": "step_5",
"name": "Note Refinement with Related Notes (Step 5 of 5)",
"description": "Final refinement incorporating actual vault-searched related notes",
"promptId": "note_refinement_with_vault",
"order": 4,
"dependencies": ["step_3", "step_4"],
"inputMapping": {
"notes": "notebook_output",
"related_notes": "related_notes"
},
"outputMapping": {
"result": "result"
},
"timeout": 300000,
"optional": false
}
])
```
#### Step 5: Create Enhanced Note Refinement Prompt
```bash
# Create the final refinement prompt that incorporates actual related notes
prompt_manager(action: "create",
id: "note_refinement_with_vault",
name: "Note Refinement with Vault Integration",
category: "analysis",
description: "Final step in the notes chain that integrates actual vault-discovered related notes with refined markdown formatting",
system_message: "You are an expert at organizing and refining knowledge notes with proper cross-referencing. Your task is to take markdown notes and enhance them with actual related notes found in the vault, creating a polished, interconnected knowledge artifact.",
user_message_template: "Please refine and enhance these markdown notes by integrating the actual related notes that were found in the vault:\n\n## Original Notes:\n{{notes}}\n\n## Related Notes Found in Vault:\n{{related_notes}}\n\n## Task:\n1. Review the original notes and related notes\n2. Integrate relevant information from the related notes\n3. Add proper cross-references and links\n4. Improve the structure and formatting\n5. Ensure the final output is a cohesive, well-organized knowledge artifact\n\nReturn the refined notes with actual cross-references to the vault notes.",
arguments: [
{"name": "notes", "description": "Original markdown notes to refine", "required": true},
{"name": "related_notes", "description": "Related notes found in the vault", "required": true}
])
```
#### Step 6: Apply Changes and Test
```bash
# Reload to apply all changes
prompt_manager(action: "reload")
# Test the updated chain
prompt_engine(command: ">>notes_modular content:'Test content to see if vault search works'")
# Verify the chain structure
prompt_manager(action: "list", filter: "notes_modular", verbose: true)
```
## Example 2: Adding a Step to Existing Chain
### Scenario: Add validation step to a processing chain
```bash
# 1. Check current chain structure
prompt_manager(action: "list", filter: "processing_chain", verbose: true)
# 2. Create validation prompt if needed
prompt_manager(action: "create",
id: "content_validator",
name: "Content Validator",
category: "validation",
description: "Validates processed content for quality and completeness",
user_message_template: "Validate this content: {{content}}\n\nCheck for:\n- Completeness\n- Accuracy\n- Format compliance\n\nReturn validation results.")
# 3. Update chain to insert validation step
prompt_manager(action: "update",
id: "processing_chain",
chain_steps: [
// ... existing steps up to where validation should be inserted ...
{
"id": "validation_step",
"name": "Content Validation",
"promptId": "content_validator",
"order": 2, // Insert at appropriate position
"dependencies": ["previous_step"],
"inputMapping": {
"content": "processed_content"
},
"outputMapping": {
"result": "validation_results"
}
},
// ... remaining steps with updated dependencies and order numbers ...
])
# 4. Apply and test
prompt_manager(action: "reload")
prompt_engine(command: ">>processing_chain input:'test data'")
```
## Example 3: Modifying Chain Step Parameters
### Scenario: Update timeout and input mappings for a step
```bash
# 1. Get current chain definition
prompt_manager(action: "list", filter: "my_chain", verbose: true)
# 2. Update with modified parameters
prompt_manager(action: "update",
id: "my_chain",
chain_steps: [
{
"id": "slow_step",
"name": "Processing Step",
"promptId": "heavy_processor",
"order": 1,
"dependencies": ["step_0"],
"inputMapping": {
"input_data": "raw_data",
"processing_mode": "thorough", // New parameter
"batch_size": 100 // New parameter
},
"outputMapping": {
"result": "processed_data"
},
"timeout": 600000, // Increased from 300000
"optional": false
}
// ... other steps ...
])
# 3. Apply changes
prompt_manager(action: "reload")
```
## Key Principles
### 1. Always Use MCP Tools
- ✅ `prompt_manager(action: "update", ...)`
- ❌ `Update(~/prompts/chain.json)`
### 2. Check Before Creating
- Use `prompt_manager(action: "list")` to see what exists
- Avoid duplicating existing functionality
### 3. Reload After Changes
- Always call `prompt_manager(action: "reload")` after modifications
- This ensures hot-reloading picks up changes
### 4. Test Changes
- Use `prompt_engine(command: ">>chain_name ...")` to test
- Verify with `prompt_manager(action: "list", verbose: true)`
### 5. Structured Data Approach
- Define complete chain_steps arrays with all required fields
- Use proper dependency management (order, dependencies arrays)
- Include all metadata (timeouts, optional flags, etc.)
## Common Pitfalls to Avoid
1. **Direct File Editing**: Never use Update(), Edit(), Write() on prompt files
2. **Partial Updates**: Always provide complete chain_steps array, not partial modifications
3. **Missing Dependencies**: Ensure step dependencies are correctly specified
4. **Skipping Reload**: Changes won't take effect without reload
5. **Wrong Order Numbers**: Step order affects execution sequence
6. **Missing Error Handling**: Consider timeout and optional settings for reliability
## Advanced Patterns
### Conditional Chain Steps
```bash
# Use optional: true for steps that may fail
{
"id": "optional_enhancement",
"name": "Enhancement Step",
"promptId": "enhancer",
"optional": true, // Won't fail chain if this step fails
"timeout": 30000 // Shorter timeout for optional steps
}
```
### Parallel Processing
```bash
# Steps with same order number execute in parallel
{
"id": "parallel_step_a",
"order": 2,
"dependencies": ["step_1"]
},
{
"id": "parallel_step_b",
"order": 2,
"dependencies": ["step_1"]
}
```
### Data Transformation
```bash
# Use inputMapping to transform data between steps
{
"inputMapping": {
"prompt_input_name": "previous_step_output_key",
"static_value": "constant_data",
"computed_value": "{{dynamic_expression}}"
}
}
```
```
--------------------------------------------------------------------------------
/server/src/frameworks/types/prompt-guidance-types.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Prompt Guidance Type Definitions
*
* Contains all types related to prompt enhancement, system prompt injection,
* and methodology-driven template processing. These types support the prompt
* guidance system that enhances MCP prompts with methodology-specific improvements.
*/
import type { ConvertedPrompt } from '../../execution/types.js';
import type { FrameworkDefinition, MethodologyEnhancement, ProcessingGuidance } from './methodology-types.js';
/**
* System prompt injection configuration
*/
export interface SystemPromptInjectionConfig {
/** Whether to inject methodology guidance into system prompts */
enabled: boolean;
/** Priority of injection (higher values override lower) */
priority: number;
/** Template for injecting methodology guidance */
injectionTemplate: string;
/** Variables available for injection template */
availableVariables: string[];
}
/**
* System prompt injection result
*/
export interface SystemPromptInjectionResult {
/** Original system prompt before injection */
originalPrompt: string;
/** Enhanced system prompt with methodology guidance */
enhancedPrompt: string;
/** Methodology guidance that was injected */
injectedGuidance: string;
/** Framework that provided the guidance */
sourceFramework: FrameworkDefinition;
/** Injection metadata */
metadata: {
injectionTime: Date;
injectionMethod: string;
variablesUsed: string[];
confidence: number;
processingTimeMs: number;
validationPassed: boolean;
error?: string;
// Phase 4: Semantic analysis metadata
semanticAware?: boolean;
semanticComplexity?: 'low' | 'medium' | 'high';
semanticConfidence?: number;
};
}
/**
* Template enhancement configuration
*/
export interface TemplateEnhancementConfig {
/** Whether to enhance templates with methodology guidance */
enabled: boolean;
/** Types of enhancements to apply */
enabledEnhancements: TemplateEnhancementType[];
/** Minimum confidence threshold for applying enhancements */
confidenceThreshold: number;
/** Maximum number of enhancements to apply */
maxEnhancements: number;
}
/**
* Types of template enhancements
*/
export type TemplateEnhancementType =
| 'structure'
| 'clarity'
| 'completeness'
| 'methodology_alignment'
| 'quality_gates';
/**
* Template enhancement result
*/
export interface TemplateEnhancementResult {
/** Original template before enhancement */
originalTemplate: string;
/** Enhanced template with methodology improvements */
enhancedTemplate: string;
/** Applied enhancements */
suggestions: string[];
/** Template processing guidance from methodology */
processingGuidance: ProcessingGuidance;
/** Framework that provided the guidance */
sourceFramework: FrameworkDefinition;
/** Enhancement metadata */
metadata: {
enhancementTime: Date;
enhancementLevel: 'minimal' | 'moderate' | 'comprehensive';
suggestionsCount: number;
validationPassed: boolean;
processingTimeMs: number;
methodologyApplied: string;
error?: string;
// Phase 4: Semantic analysis metadata
semanticAware?: boolean;
semanticComplexity?: 'low' | 'medium' | 'high';
semanticConfidence?: number;
semanticEnhancementsApplied?: string[];
};
/** Validation result */
validation: {
passed: boolean;
score: number;
issues: string[];
recommendations: string[];
};
}
/**
* Applied enhancement details
*/
export interface AppliedEnhancement {
/** Type of enhancement applied */
type: TemplateEnhancementType;
/** Description of what was enhanced */
description: string;
/** Location in template where enhancement was applied */
location: 'system' | 'user' | 'arguments' | 'metadata';
/** Enhancement content that was added/modified */
content: string;
/** Confidence in this enhancement */
confidence: number;
/** Methodology justification for the enhancement */
justification: string;
}
/**
* Methodology tracking state
*/
export interface MethodologyTrackingState {
/** Currently active methodology */
activeMethodology: string;
/** Previous methodology (for switch tracking) */
previousMethodology: string | null;
/** When the current methodology was activated */
activatedAt: Date;
/** Reason for the current methodology selection */
activationReason: string;
/** Whether methodology tracking is enabled */
trackingEnabled: boolean;
/** Methodology switch history */
switchHistory: MethodologySwitchRecord[];
}
/**
* Methodology switch record
*/
export interface MethodologySwitchRecord {
/** When the switch occurred */
timestamp: Date;
/** Methodology switched from */
fromMethodology: string;
/** Methodology switched to */
toMethodology: string;
/** Reason for the switch */
reason: string;
/** Whether the switch was successful */
successful: boolean;
/** Switch duration in milliseconds */
duration: number;
}
/**
* Methodology state change event
*/
export interface MethodologyStateChangeEvent {
/** Type of state change */
type: 'switch' | 'enable' | 'disable' | 'error';
/** Previous state */
previousState: MethodologyTrackingState;
/** New state */
newState: MethodologyTrackingState;
/** Event timestamp */
timestamp: Date;
/** Additional event context */
context?: Record<string, any>;
}
/**
* Prompt guidance configuration
*/
export interface PromptGuidanceConfig {
/** System prompt injection configuration */
systemPromptInjection: SystemPromptInjectionConfig;
/** Template enhancement configuration */
templateEnhancement: TemplateEnhancementConfig;
/** Methodology tracking configuration */
methodologyTracking: {
enabled: boolean;
persistState: boolean;
trackSwitches: boolean;
maxHistoryEntries: number;
};
}
/**
* Comprehensive prompt guidance result
*/
export interface PromptGuidanceResult {
/** Original prompt before guidance was applied */
originalPrompt: ConvertedPrompt;
/** Enhanced prompt with all guidance applied */
enhancedPrompt: ConvertedPrompt;
/** System prompt injection result */
systemPromptInjection: SystemPromptInjectionResult | null;
/** Template enhancement result */
templateEnhancement: TemplateEnhancementResult | null;
/** Applied methodology enhancement */
methodologyEnhancement: MethodologyEnhancement | null;
/** Guidance metadata */
metadata: {
guidanceTime: Date;
activeMethodology: string;
totalEnhancements: number;
confidenceScore: number;
processingTime: number;
};
}
/**
* Prompt guidance analytics
*/
export interface PromptGuidanceAnalytics {
/** Total number of prompts enhanced */
totalEnhanced: number;
/** Enhancement success rate */
successRate: number;
/** Average enhancement confidence */
averageConfidence: number;
/** Most common enhancement types */
commonEnhancements: Record<TemplateEnhancementType, number>;
/** Methodology usage distribution */
methodologyUsage: Record<string, {
count: number;
averageConfidence: number;
successRate: number;
}>;
/** Performance metrics */
performance: {
averageProcessingTime: number;
maxProcessingTime: number;
totalProcessingTime: number;
};
}
/**
* Framework state information for prompt guidance
*/
export interface FrameworkStateInfo {
/** Whether framework system is enabled */
frameworkSystemEnabled: boolean;
/** Active framework definition */
activeFramework: FrameworkDefinition | null;
/** Available frameworks */
availableFrameworks: FrameworkDefinition[];
/** Framework health status */
healthStatus: 'healthy' | 'degraded' | 'error';
/** Framework switching metrics */
switchingMetrics: {
totalSwitches: number;
successfulSwitches: number;
averageResponseTime: number;
};
}
/**
* Prompt guidance service interface
*/
export interface IPromptGuidanceService {
/**
* Apply comprehensive guidance to a prompt
*/
applyGuidance(
prompt: ConvertedPrompt,
config?: Partial<PromptGuidanceConfig>
): Promise<PromptGuidanceResult>;
/**
* Get current methodology tracking state
*/
getMethodologyState(): MethodologyTrackingState;
/**
* Get framework state information
*/
getFrameworkState(): FrameworkStateInfo;
/**
* Get guidance analytics
*/
getAnalytics(): PromptGuidanceAnalytics;
/**
* Reset analytics and tracking data
*/
resetAnalytics(): void;
}
/**
* Methodology state information (Phase 3)
*/
export interface MethodologyState {
/** Currently active methodology */
activeMethodology: string;
/** Previous methodology (for switch tracking) */
previousMethodology: string | null;
/** When the current methodology was activated */
switchedAt: Date;
/** Reason for the current methodology selection */
switchReason: string;
/** Whether methodology system is healthy */
isHealthy: boolean;
/** Whether methodology system is enabled */
methodologySystemEnabled: boolean;
/** Methodology switching metrics */
switchingMetrics: {
switchCount: number;
averageResponseTime: number;
errorCount: number;
};
}
/**
* Methodology switch request (Phase 3)
*/
export interface MethodologySwitchRequest {
/** Target methodology to switch to */
targetMethodology: string;
/** Reason for the switch */
reason?: string;
/** Additional criteria for the switch */
criteria?: Record<string, any>;
}
/**
* Methodology system health information (Phase 3)
*/
export interface MethodologyHealth {
/** System health status */
status: "healthy" | "degraded" | "error";
/** Currently active methodology */
activeMethodology: string;
/** Whether methodology system is enabled */
methodologySystemEnabled: boolean;
/** Last switch time */
lastSwitchTime: Date | null;
/** Switching performance metrics */
switchingMetrics: {
totalSwitches: number;
successfulSwitches: number;
failedSwitches: number;
averageResponseTime: number;
};
/** Current health issues */
issues: string[];
}
/**
* Persisted methodology state for disk storage (Phase 3)
*/
export interface PersistedMethodologyState {
/** State format version */
version: string;
/** Whether methodology system is enabled */
methodologySystemEnabled: boolean;
/** Currently active methodology */
activeMethodology: string;
/** Last switch timestamp as ISO string */
lastSwitchedAt: string;
/** Reason for current state */
switchReason: string;
}
/**
* Template processing guidance from methodology guides (Phase 3)
* Extends the base ProcessingGuidance interface
*/
export interface TemplateProcessingGuidance {
// Methodology-specific processing steps
processingSteps: Array<{
id: string;
name: string;
action: string;
methodologyPhase: string;
dependencies: string[];
expected_output: string;
}>;
// Template enhancement suggestions
templateEnhancements: {
systemPromptAdditions: string[];
userPromptModifications: string[];
contextualHints: string[];
};
// Execution flow guidance
executionFlow: {
preProcessingSteps: string[];
postProcessingSteps: string[];
validationSteps: string[];
};
}
```
--------------------------------------------------------------------------------
/server/src/types/index.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Consolidated Type Index for MCP Prompts Server
*
* This module serves as the central type export hub, importing from domain-specific
* type files and re-exporting them for easy consumption. Types are now organized
* by domain for better maintainability and reduced duplication.
*
* Architecture: Domain-specific types -> This index -> Consumer modules
*/
// ===== Import Domain-Specific Types =====
// Core configuration and protocol types
export type {
Config,
ServerConfig,
TransportConfig,
TransportsConfig,
LoggingConfig,
AnalysisMode,
LLMProvider,
LLMIntegrationConfig,
SemanticAnalysisConfig,
AnalysisConfig,
ToolDescriptionsOptions,
Message,
MessageContent,
MessageRole,
TextMessageContent,
BaseMessageContent
} from '../types.js';
// Prompt system types
export type {
PromptArgument,
Category,
PromptData,
PromptFile,
PromptsConfig,
PromptsConfigFile,
PromptsFile,
PromptFileContent,
CategoryPromptsResult,
CategoryValidationResult,
CategoryStatistics,
CategoryPromptRelationship
} from '../prompts/types.js';
// Execution system types
export type {
ConvertedPrompt,
ChainStep,
ExecutionStrategyType,
ExecutionType,
BaseExecutionContext,
UnifiedExecutionResult,
ExecutionStrategy,
ChainExecutionResult,
ChainStepResult,
ChainExecutionState,
EnhancedChainExecutionOptions,
TemplateContext,
ValidationResult,
ExecutionStats,
PerformanceMetrics
} from '../execution/types.js';
// Import additional types needed for interfaces in this file
import type {
ChainStep,
EnhancedChainExecutionOptions,
ChainStepResult
} from '../execution/types.js';
import type {
GateStatus,
StepResult
} from '../gates/types.js';
// Gate system types
export type {
GateDefinition,
GateRequirement,
GateRequirementType,
GateStatus,
GateEvaluationResult,
ValidationContext,
GateActivationResult,
LightweightGateDefinition,
GatePassCriteria,
ValidationCheck,
GatesConfig,
StepResult,
GateType
} from '../gates/types.js';
// Framework system types (consolidated in Phase 2)
export type {
FrameworkDefinition,
FrameworkExecutionContext,
FrameworkSelectionCriteria,
FrameworkMethodology,
IMethodologyGuide,
FrameworkStateInfo,
IntegratedAnalysisResult,
FrameworkSwitchingConfig
} from '../frameworks/types/index.js';
// ===== Additional System Types =====
// Text Reference System Types
export interface TextReference {
id: string;
title: string;
content: string;
createdAt: number;
lastUsed: number;
}
export interface TextReferenceStore {
references: TextReference[];
maxAge: number; // Maximum age in milliseconds before cleanup
maxSize: number; // Maximum number of references to store
}
// Conversation History Types
export interface ConversationHistoryItem {
role: "user" | "assistant";
content: string;
timestamp: number;
isProcessedTemplate?: boolean; // Flag to indicate if this is a processed template rather than original user input
}
// Advanced Chain Execution Types
export interface EnhancedChainExecutionContext {
chainId: string;
chainName: string;
startTime: number;
executionOptions: EnhancedChainExecutionOptions;
// Enhanced step tracking
allSteps: ChainStep[]; // All steps in the chain
completedSteps: Set<string>; // Step IDs that have completed successfully
failedSteps: Set<string>; // Step IDs that have failed
skippedSteps: Set<string>; // Step IDs that were skipped due to dependencies/conditions
stepResults: Record<string, StepResult>; // Detailed results from each step
// Dependency management
executionPlan?: {
executionOrder: string[]; // Topologically sorted step execution order
parallelGroups: Map<string, string[]>; // Parallel execution groups
};
// Advanced execution state
currentPhase: 'planning' | 'executing' | 'completed' | 'failed';
activeParallelGroups: Map<string, string[]>; // Currently executing parallel groups
retryCount: Record<string, number>; // Retry attempts per step
// Gate validation tracking
gateValidationResults: Record<string, GateStatus[]>; // Gate results per step
}
// API Response Types
export interface ApiResponse {
success: boolean;
message: string;
data?: unknown;
}
export interface ToolResponse {
content: Array<{
type: "text";
text: string;
}>;
isError?: boolean;
// Structured output data for programmatic access
structuredContent?: {
// Gate validation results in structured format
gateValidation?: {
enabled: boolean;
passed: boolean;
totalGates: number;
failedGates: Array<{
gateId: string;
gateName: string;
reason: string;
score?: number;
requirements: string[];
evaluationTime?: number;
}>;
passedGates?: Array<{
gateId: string;
gateName: string;
score?: number;
}>;
executionTime: number;
retryCount?: number;
};
// Core execution metadata
executionMetadata?: {
executionId: string;
executionType: "prompt" | "template" | "chain";
startTime: number;
endTime: number;
executionTime: number;
frameworkUsed?: string;
frameworkEnabled: boolean;
stepsExecuted?: number;
sessionId?: string;
memoryUsage?: {
heapUsed: number;
heapTotal: number;
external: number;
};
};
// Analytics and performance data
analytics?: {
totalExecutions: number;
successRate: number;
averageExecutionTime: number;
frameworkSwitches?: number;
gateValidationCount?: number;
errorCount?: number;
uptime: number;
};
// Chain execution progress (for chain operations)
chainProgress?: {
chainId: string;
chainName: string;
currentStep: number;
totalSteps: number;
status: "pending" | "running" | "completed" | "failed" | "paused";
steps: Array<{
stepIndex: number;
stepName: string;
promptId: string;
status: "pending" | "running" | "completed" | "failed" | "skipped";
startTime?: number;
endTime?: number;
duration?: number;
result?: string;
error?: string;
}>;
autoExecute: boolean;
sessionStrategy?: "auto" | "explicit" | "new";
executionOptions?: {
stepConfirmation: boolean;
gateValidation: boolean;
frameworkEnabled: boolean;
};
};
// Error information (for failed operations)
errorInfo?: {
errorCode: string;
errorType: "validation" | "execution" | "system" | "client" | "configuration";
message: string;
details?: any;
timestamp: number;
severity: "low" | "medium" | "high" | "critical";
suggestedActions?: string[];
relatedComponents?: string[];
};
// Tool-specific structured data
[key: string]: any;
};
}
// Tool Description Types
export interface ToolParameter {
description?: string;
examples?: string[];
}
export interface ToolDescription {
description: string;
parameters?: Record<string, ToolParameter | string>;
shortDescription?: string;
category?: string;
frameworkAware?: {
enabled?: string;
disabled?: string;
parametersEnabled?: Record<string, ToolParameter | string>;
parametersDisabled?: Record<string, ToolParameter | string>;
methodologies?: Record<string, string>;
methodologyParameters?: Record<string, Record<string, ToolParameter | string>>;
};
}
export interface ToolDescriptionsConfig {
version: string;
lastUpdated?: string;
tools: Record<string, ToolDescription>;
}
// Server Management Types
export interface ServerRefreshOptions {
restart?: boolean;
reason?: string;
}
export interface ServerState {
isStarted: boolean;
transport: string;
port?: number;
startTime: number;
}
// File Operation Types
export interface FileOperation {
(): Promise<boolean>;
}
export interface ModificationResult {
success: boolean;
message: string;
}
// Express and Transport Types
export interface ExpressRequest {
body: any;
params: Record<string, string>;
headers: Record<string, string>;
ip: string;
method: string;
url: string;
}
export interface ExpressResponse {
json: (data: any) => void;
status: (code: number) => ExpressResponse;
send: (data: any) => void;
setHeader: (name: string, value: string) => void;
end: () => void;
sendStatus: (code: number) => void;
on: (event: string, callback: () => void) => void;
}
// Execution State Types
export interface ExecutionState {
type: 'single' | 'chain';
promptId: string;
status: 'pending' | 'running' | 'waiting_gate' | 'completed' | 'failed' | 'retrying';
currentStep?: number;
totalSteps?: number;
gates: GateStatus[];
results: Record<string, string | ChainStepResult>;
metadata: {
startTime: number;
endTime?: number;
executionMode?: 'prompt' | 'template' | 'chain';
stepConfirmation?: boolean;
gateValidation?: boolean;
sessionId?: string; // For chain session management
};
}
// Enhanced Chain Execution Types
export interface EnhancedChainExecutionState {
chainId: string;
currentStepIndex: number;
totalSteps: number;
startTime: number;
status: 'pending' | 'running' | 'waiting_gate' | 'completed' | 'failed';
stepResults: Record<string, StepResult>;
gates: Record<string, GateStatus>;
executionMode: 'auto' | 'chain';
gateValidation: boolean;
stepConfirmation: boolean;
}
// Chain execution progress tracking
export interface ChainExecutionProgress {
chainId: string;
chainName: string;
currentStep: number;
totalSteps: number;
status: 'pending' | 'running' | 'completed' | 'failed' | 'paused';
steps: ChainStepProgress[];
startTime: number;
endTime?: number;
duration?: number;
errorCount: number;
autoExecute: boolean;
}
export interface ChainStepProgress {
stepIndex: number;
stepName: string;
promptId: string;
status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
startTime?: number;
endTime?: number;
duration?: number;
result?: string;
error?: string;
gateResults?: GateStatus[];
}
// Auto-execution configuration for chains
export interface AutoExecutionConfig {
enabled: boolean;
stepConfirmation: boolean;
gateValidation: boolean;
pauseOnError: boolean;
maxRetries: number;
retryDelay: number; // milliseconds
}
// Constants and Enums
export const MAX_HISTORY_SIZE = 100;
export enum LogLevel {
DEBUG = "DEBUG",
INFO = "INFO",
WARN = "WARN",
ERROR = "ERROR",
}
export enum TransportType {
STDIO = "stdio",
SSE = "sse",
}
export enum ExecutionMode {
AUTO = "auto",
TEMPLATE = "template",
CHAIN = "chain",
}
export enum StepStatus {
PENDING = "pending",
RUNNING = "running",
COMPLETED = "completed",
FAILED = "failed",
SKIPPED = "skipped",
}
// ===== End of Consolidated Type Definitions =====
// Types are now organized by domain for better maintainability:
// - Core types: ../types.js
// - Prompt types: ../prompts/types.js
// - Execution types: ../execution/types.js
// - Gate types: ../gates/types.js
// - Framework types: ../frameworks/types/index.js
```
--------------------------------------------------------------------------------
/server/tests/enhanced-validation/environment-validation/environment-parity-checker.js:
--------------------------------------------------------------------------------
```javascript
/**
* Environment Parity Validation System
*
* Validates consistency between local and CI environments to prevent
* environment-specific failures in GitHub Actions.
*/
import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
/**
* Environment Parity Checker
*
* Detects environment differences that could cause CI failures
*/
export class EnvironmentParityChecker {
constructor(logger) {
this.logger = logger;
this.projectRoot = path.resolve(__dirname, '../../..');
}
/**
* Validate Node.js version against package.json requirements
*/
async validateNodeVersion() {
try {
const packagePath = path.join(this.projectRoot, 'package.json');
const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
const currentVersion = process.version;
const engineRequirement = packageJson.engines?.node;
if (!engineRequirement) {
return {
valid: true,
currentVersion,
requiredVersion: 'Not specified',
warning: 'No Node.js version requirement specified in package.json'
};
}
// Parse version requirement (handle >=16, ^18, etc.)
const versionMatch = engineRequirement.match(/([>=^~]*)([0-9.]+)/);
if (!versionMatch) {
return {
valid: false,
currentVersion,
requiredVersion: engineRequirement,
error: 'Invalid version requirement format'
};
}
const [, operator, requiredVersion] = versionMatch;
const currentMajor = parseInt(currentVersion.slice(1).split('.')[0]);
const requiredMajor = parseInt(requiredVersion.split('.')[0]);
let compatible = false;
let details = '';
switch (operator) {
case '>=':
compatible = currentMajor >= requiredMajor;
details = `Current ${currentMajor} >= Required ${requiredMajor}`;
break;
case '^':
compatible = currentMajor >= requiredMajor;
details = `Current ${currentMajor} compatible with ^${requiredMajor}`;
break;
case '~':
compatible = currentMajor === requiredMajor;
details = `Current ${currentMajor} matches ~${requiredMajor}`;
break;
default:
compatible = currentMajor >= requiredMajor;
details = `Current ${currentMajor} >= Required ${requiredMajor} (default check)`;
}
return {
valid: compatible,
currentVersion,
requiredVersion: engineRequirement,
details,
recommendation: compatible ? null : `Upgrade Node.js to meet requirement: ${engineRequirement}`
};
} catch (error) {
return {
valid: false,
error: `Node version validation failed: ${error.message}`,
currentVersion: process.version
};
}
}
/**
* Validate environment variables consistency
*/
async validateEnvironmentVariables() {
const criticalEnvVars = [
'NODE_ENV',
'MCP_SERVER_ROOT',
'MCP_PROMPTS_CONFIG_PATH'
];
const envReport = {
valid: true,
variables: {},
missing: [],
recommendations: []
};
for (const varName of criticalEnvVars) {
const value = process.env[varName];
envReport.variables[varName] = {
defined: value !== undefined,
value: value || null,
source: 'process.env'
};
if (!value && varName === 'NODE_ENV') {
envReport.missing.push(varName);
envReport.recommendations.push('Set NODE_ENV=test for testing environments');
envReport.valid = false;
}
}
// Check for CI-specific variables
const ciIndicators = ['CI', 'GITHUB_ACTIONS', 'ACT'];
const ciDetected = ciIndicators.some(varName => process.env[varName]);
envReport.ciEnvironment = {
detected: ciDetected,
indicators: ciIndicators.filter(varName => process.env[varName]),
isLocal: !ciDetected
};
// Platform-specific environment checks
envReport.platform = {
os: process.platform,
arch: process.arch,
isWindows: process.platform === 'win32',
isWSL: process.env.WSL_DISTRO_NAME !== undefined
};
return envReport;
}
/**
* Validate filesystem behavior for cross-platform compatibility
*/
async validateFilesystemBehavior() {
const testDir = path.join(this.projectRoot, 'tests', 'temp');
const fsReport = {
valid: true,
pathSeparator: path.sep,
platform: process.platform,
issues: [],
recommendations: []
};
try {
// Ensure test directory exists
if (!fs.existsSync(testDir)) {
fs.mkdirSync(testDir, { recursive: true });
}
// Test case sensitivity
const testFile1 = path.join(testDir, 'Test.txt');
const testFile2 = path.join(testDir, 'test.txt');
fs.writeFileSync(testFile1, 'test1');
try {
fs.writeFileSync(testFile2, 'test2');
// If both files exist, filesystem is case-sensitive
const file1Exists = fs.existsSync(testFile1);
const file2Exists = fs.existsSync(testFile2);
fsReport.caseSensitive = file1Exists && file2Exists;
// Clean up test files
try { fs.unlinkSync(testFile1); } catch {}
try { fs.unlinkSync(testFile2); } catch {}
} catch (error) {
// If writing second file fails, filesystem is case-insensitive
fsReport.caseSensitive = false;
try { fs.unlinkSync(testFile1); } catch {}
}
// Test path length limits
const longPath = path.join(testDir, 'a'.repeat(255));
try {
fs.writeFileSync(longPath, 'test');
fs.unlinkSync(longPath);
fsReport.supportsLongPaths = true;
} catch (error) {
fsReport.supportsLongPaths = false;
fsReport.issues.push('Long path support limited');
}
// Test symbolic links (if supported)
try {
const linkTarget = path.join(testDir, 'target.txt');
const linkPath = path.join(testDir, 'symlink.txt');
fs.writeFileSync(linkTarget, 'target');
fs.symlinkSync(linkTarget, linkPath);
fsReport.supportsSymlinks = fs.lstatSync(linkPath).isSymbolicLink();
fs.unlinkSync(linkPath);
fs.unlinkSync(linkTarget);
} catch (error) {
fsReport.supportsSymlinks = false;
fsReport.issues.push('Symbolic link support unavailable');
}
// Clean up test directory
try {
fs.rmdirSync(testDir);
} catch (error) {
// Directory might not be empty or might not exist
}
} catch (error) {
fsReport.valid = false;
fsReport.error = `Filesystem validation failed: ${error.message}`;
}
return fsReport;
}
/**
* Validate package dependencies consistency
*/
async validatePackageDependencies() {
try {
const packagePath = path.join(this.projectRoot, 'package.json');
const lockfilePath = path.join(this.projectRoot, 'package-lock.json');
const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
let lockfileExists = false;
let lockfileData = null;
try {
lockfileData = JSON.parse(fs.readFileSync(lockfilePath, 'utf8'));
lockfileExists = true;
} catch (error) {
// Lockfile doesn't exist or is invalid
}
const dependencyReport = {
valid: true,
packageJsonExists: true,
lockfileExists,
dependencies: Object.keys(packageJson.dependencies || {}),
devDependencies: Object.keys(packageJson.devDependencies || {}),
issues: [],
recommendations: []
};
// Check for critical MCP dependencies
const criticalDeps = ['@modelcontextprotocol/sdk'];
const missingCritical = criticalDeps.filter(dep =>
!dependencyReport.dependencies.includes(dep)
);
if (missingCritical.length > 0) {
dependencyReport.valid = false;
dependencyReport.issues.push(`Missing critical dependencies: ${missingCritical.join(', ')}`);
dependencyReport.recommendations.push('Install missing MCP SDK dependencies');
}
// Check lockfile consistency (if exists)
if (lockfileExists && lockfileData) {
const lockfileDeps = Object.keys(lockfileData.dependencies || {});
const packageDeps = [...dependencyReport.dependencies, ...dependencyReport.devDependencies];
const mismatchedDeps = packageDeps.filter(dep => !lockfileDeps.includes(dep));
if (mismatchedDeps.length > 0) {
dependencyReport.issues.push(`Dependencies not in lockfile: ${mismatchedDeps.join(', ')}`);
dependencyReport.recommendations.push('Run npm install to update lockfile');
}
}
if (!lockfileExists) {
dependencyReport.recommendations.push('Generate package-lock.json for dependency consistency');
}
return dependencyReport;
} catch (error) {
return {
valid: false,
error: `Dependency validation failed: ${error.message}`,
packageJsonExists: false
};
}
}
/**
* Generate comprehensive environment parity report
*/
async generateParityReport() {
this.logger.debug('[ENV PARITY] Starting comprehensive environment validation');
const startTime = Date.now();
const nodeVersion = await this.validateNodeVersion();
const envVars = await this.validateEnvironmentVariables();
const filesystem = await this.validateFilesystemBehavior();
const dependencies = await this.validatePackageDependencies();
const validationTime = Date.now() - startTime;
const overallValid = nodeVersion.valid && envVars.valid && filesystem.valid && dependencies.valid;
const report = {
timestamp: new Date(),
validationTime,
overall: {
valid: overallValid,
environment: envVars.ciEnvironment.detected ? 'CI' : 'Local',
platform: process.platform,
nodeVersion: process.version
},
components: {
nodeVersion,
environmentVariables: envVars,
filesystem,
dependencies
},
recommendations: [
...nodeVersion.recommendation ? [nodeVersion.recommendation] : [],
...envVars.recommendations,
...filesystem.recommendations,
...dependencies.recommendations
]
};
this.logger.debug('[ENV PARITY] Environment validation completed', {
valid: overallValid,
validationTime,
platform: process.platform
});
return report;
}
/**
* Quick environment compatibility check
*/
async quickCompatibilityCheck() {
const nodeCheck = await this.validateNodeVersion();
const envCheck = await this.validateEnvironmentVariables();
return {
compatible: nodeCheck.valid && envCheck.valid,
issues: [
...(nodeCheck.valid ? [] : [nodeCheck.error || nodeCheck.recommendation]),
...(envCheck.valid ? [] : envCheck.recommendations)
].filter(Boolean)
};
}
}
/**
* Factory function for creating checker instance
*/
export function createEnvironmentParityChecker(logger) {
return new EnvironmentParityChecker(logger);
}
```
--------------------------------------------------------------------------------
/server/src/chain-session/manager.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Chain Session Manager
*
* Manages chain execution sessions, providing the bridge between MCP session IDs
* and the chain state management in ConversationManager. This enables stateful
* chain execution across multiple MCP tool calls.
*/
import { Logger } from "../logging/index.js";
import { ConversationManager } from "../text-references/conversation.js";
import { TextReferenceManager } from "../text-references/index.js";
import { ChainState } from "../mcp-tools/prompt-engine/core/types.js";
/**
* Session information for chain execution
*/
export interface ChainSession {
sessionId: string;
chainId: string;
state: ChainState;
currentStepId?: string;
executionOrder: number[];
startTime: number;
lastActivity: number;
originalArgs: Record<string, any>;
}
/**
* Chain Session Manager class
*
* Coordinates session state between MCP protocol and conversation manager.
* Provides session-aware context retrieval for chain execution.
*/
export class ChainSessionManager {
private logger: Logger;
private conversationManager: ConversationManager;
private textReferenceManager: TextReferenceManager;
private activeSessions: Map<string, ChainSession> = new Map();
private chainSessionMapping: Map<string, Set<string>> = new Map(); // chainId -> sessionIds
constructor(logger: Logger, conversationManager: ConversationManager, textReferenceManager: TextReferenceManager) {
this.logger = logger;
this.conversationManager = conversationManager;
this.textReferenceManager = textReferenceManager;
// Integrate with conversation manager (with enhanced null checking for testing)
try {
if (conversationManager !== null && conversationManager !== undefined &&
conversationManager.setChainSessionManager &&
typeof conversationManager.setChainSessionManager === 'function') {
conversationManager.setChainSessionManager(this);
} else {
if (this.logger) {
this.logger.debug("ConversationManager is null or missing setChainSessionManager method - running in test mode");
}
}
} catch (error) {
// Handle any errors during integration (e.g., null references during testing)
if (this.logger) {
this.logger.debug(`Failed to integrate with conversation manager: ${error instanceof Error ? error.message : String(error)}`);
}
}
if (this.logger) {
this.logger.debug("ChainSessionManager initialized with conversation and text reference manager integration");
}
}
/**
* Create a new chain session
*/
createSession(sessionId: string, chainId: string, totalSteps: number, originalArgs: Record<string, any> = {}): ChainSession {
const session: ChainSession = {
sessionId,
chainId,
state: {
currentStep: 0,
totalSteps,
lastUpdated: Date.now()
},
executionOrder: [],
startTime: Date.now(),
lastActivity: Date.now(),
originalArgs
};
this.activeSessions.set(sessionId, session);
// Track chain to session mapping
if (!this.chainSessionMapping.has(chainId)) {
this.chainSessionMapping.set(chainId, new Set());
}
this.chainSessionMapping.get(chainId)!.add(sessionId);
// Sync with conversation manager
this.conversationManager.setChainState(chainId, 0, totalSteps);
this.logger.debug(`Created chain session ${sessionId} for chain ${chainId} with ${totalSteps} steps`);
return session;
}
/**
* Get session by ID
*/
getSession(sessionId: string): ChainSession | undefined {
const session = this.activeSessions.get(sessionId);
if (session) {
session.lastActivity = Date.now();
}
return session;
}
/**
* Update session state after step completion
*/
updateSessionState(sessionId: string, stepNumber: number, stepResult: string, stepMetadata?: any): boolean {
const session = this.activeSessions.get(sessionId);
if (!session) {
this.logger.warn(`Attempted to update non-existent session: ${sessionId}`);
return false;
}
// Update session state
session.state.currentStep = stepNumber + 1; // Move to next step
session.state.lastUpdated = Date.now();
session.lastActivity = Date.now();
session.executionOrder.push(stepNumber);
// Store result in text reference manager (single source of truth)
this.textReferenceManager.storeChainStepResult(
session.chainId,
stepNumber,
stepResult,
stepMetadata
);
// Update conversation manager state for coordination
this.conversationManager.setChainState(
session.chainId,
session.state.currentStep,
session.state.totalSteps
);
this.logger.debug(`Updated session ${sessionId}: step ${stepNumber} completed, moved to step ${session.state.currentStep}`);
return true;
}
/**
* Get chain context for session - this is the critical method for fixing contextData
*/
getChainContext(sessionId: string): Record<string, any> {
const session = this.activeSessions.get(sessionId);
if (!session) {
this.logger.debug(`No session found for ${sessionId}, returning empty context`);
return {};
}
// Get chain variables from text reference manager (single source of truth)
const chainVariables = this.textReferenceManager.buildChainVariables(session.chainId);
// Merge with session-specific context
const contextData: Record<string, any> = {
// Core session info
session_id: sessionId,
current_step: session.state.currentStep,
total_steps: session.state.totalSteps,
execution_order: session.executionOrder,
// Chain variables (step results, etc.) from TextReferenceManager
...chainVariables
};
this.logger.debug(`Retrieved context for session ${sessionId}: ${Object.keys(contextData).length} context variables`);
return contextData;
}
/**
* Get original arguments for session
*/
getOriginalArgs(sessionId: string): Record<string, any> {
const session = this.activeSessions.get(sessionId);
return session?.originalArgs || {};
}
/**
* Check if session exists and is active
*/
hasActiveSession(sessionId: string): boolean {
return this.activeSessions.has(sessionId);
}
/**
* Check if chain has any active sessions
*/
hasActiveSessionForChain(chainId: string): boolean {
const sessionIds = this.chainSessionMapping.get(chainId);
return sessionIds ? sessionIds.size > 0 : false;
}
/**
* Get active session for chain (returns first active session)
*/
getActiveSessionForChain(chainId: string): ChainSession | undefined {
const sessionIds = this.chainSessionMapping.get(chainId);
if (!sessionIds || sessionIds.size === 0) {
return undefined;
}
// Return the most recently active session
let mostRecentSession: ChainSession | undefined;
let mostRecentActivity = 0;
for (const sessionId of sessionIds) {
const session = this.activeSessions.get(sessionId);
if (session && session.lastActivity > mostRecentActivity) {
mostRecentSession = session;
mostRecentActivity = session.lastActivity;
}
}
return mostRecentSession;
}
/**
* Clear session
*/
clearSession(sessionId: string): boolean {
const session = this.activeSessions.get(sessionId);
if (!session) {
return false;
}
// Remove from chain mapping
const chainSessions = this.chainSessionMapping.get(session.chainId);
if (chainSessions) {
chainSessions.delete(sessionId);
if (chainSessions.size === 0) {
this.chainSessionMapping.delete(session.chainId);
}
}
// Remove session
this.activeSessions.delete(sessionId);
this.logger.debug(`Cleared session ${sessionId} for chain ${session.chainId}`);
return true;
}
/**
* Clear all sessions for a chain
*/
clearSessionsForChain(chainId: string): void {
const sessionIds = this.chainSessionMapping.get(chainId);
if (!sessionIds) {
return;
}
// Clear all sessions
sessionIds.forEach(sessionId => {
this.activeSessions.delete(sessionId);
});
// Clear mapping
this.chainSessionMapping.delete(chainId);
// Clear step results from text reference manager
this.textReferenceManager.clearChainStepResults(chainId);
this.logger.debug(`Cleared all sessions for chain ${chainId}`);
}
/**
* Cleanup stale sessions (older than 1 hour)
*/
cleanupStaleSessions(): number {
const oneHourAgo = Date.now() - 3600000;
let cleaned = 0;
for (const [sessionId, session] of this.activeSessions) {
if (session.lastActivity < oneHourAgo) {
this.clearSession(sessionId);
cleaned++;
}
}
if (cleaned > 0) {
this.logger.info(`Cleaned up ${cleaned} stale chain sessions`);
}
return cleaned;
}
/**
* Get session statistics
*/
getSessionStats(): {
totalSessions: number;
totalChains: number;
averageStepsPerChain: number;
oldestSessionAge: number;
} {
const totalSessions = this.activeSessions.size;
const totalChains = this.chainSessionMapping.size;
let totalSteps = 0;
let oldestSessionTime = Date.now();
for (const session of this.activeSessions.values()) {
totalSteps += session.state.currentStep;
if (session.startTime < oldestSessionTime) {
oldestSessionTime = session.startTime;
}
}
return {
totalSessions,
totalChains,
averageStepsPerChain: totalChains > 0 ? totalSteps / totalChains : 0,
oldestSessionAge: Date.now() - oldestSessionTime
};
}
/**
* Validate session integrity
*/
validateSession(sessionId: string): { valid: boolean; issues: string[] } {
const session = this.activeSessions.get(sessionId);
const issues: string[] = [];
if (!session) {
issues.push("Session not found");
return { valid: false, issues };
}
// Check if conversation manager has corresponding state
const conversationState = this.conversationManager.getChainState(session.chainId);
if (!conversationState) {
issues.push("No corresponding conversation state found");
} else {
// Check state consistency
if (conversationState.currentStep !== session.state.currentStep) {
issues.push(`State mismatch: session=${session.state.currentStep}, conversation=${conversationState.currentStep}`);
}
if (conversationState.totalSteps !== session.state.totalSteps) {
issues.push(`Step count mismatch: session=${session.state.totalSteps}, conversation=${conversationState.totalSteps}`);
}
}
// Check for stale session
const hoursSinceActivity = (Date.now() - session.lastActivity) / 3600000;
if (hoursSinceActivity > 1) {
issues.push(`Session stale: ${hoursSinceActivity.toFixed(1)} hours since last activity`);
}
return { valid: issues.length === 0, issues };
}
}
/**
* Create and configure a chain session manager
*/
export function createChainSessionManager(
logger: Logger,
conversationManager: ConversationManager,
textReferenceManager: TextReferenceManager
): ChainSessionManager {
return new ChainSessionManager(logger, conversationManager, textReferenceManager);
}
```
--------------------------------------------------------------------------------
/server/src/execution/context/framework-injector.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Framework Injector - Phase 3
* Handles framework system prompt injection into execution context
* Integrates with FrameworkManager to provide methodology-based system prompts
*/
import { Logger } from "../../logging/index.js";
import { ConvertedPrompt } from "../../types/index.js";
import { FrameworkManager } from "../../frameworks/framework-manager.js";
import {
FrameworkExecutionContext,
FrameworkSelectionCriteria
} from "../../frameworks/types/index.js";
import { FrameworkStateManager } from "../../frameworks/framework-state-manager.js";
import { ContentAnalysisResult } from "../../semantic/configurable-semantic-analyzer.js";
import {
IMethodologyGuide,
MethodologyEnhancement
} from "../../frameworks/types/index.js";
/**
* Framework injection result
*/
export interface FrameworkInjectionResult {
// Original prompt (unchanged)
originalPrompt: ConvertedPrompt;
// Framework context
frameworkContext: FrameworkExecutionContext;
// Enhanced prompt with framework system prompt
enhancedPrompt: ConvertedPrompt & {
frameworkSystemPrompt?: string;
frameworkGuidelines?: string[];
frameworkMetadata?: {
selectedFramework: string;
selectionReason: string;
confidence: number;
};
methodologyEnhancement?: MethodologyEnhancement;
};
// Injection metadata
injectionMetadata: {
injectedAt: Date;
frameworkId: string;
injectionMethod: 'system_prompt' | 'user_prefix' | 'guidelines';
originalSystemMessage?: string;
};
}
/**
* Framework injection configuration
*/
export interface FrameworkInjectionConfig {
enableInjection: boolean;
injectionMethod: 'system_prompt' | 'user_prefix' | 'guidelines';
preserveOriginalSystemMessage: boolean;
includeFrameworkMetadata: boolean;
userPreferenceOverride?: string;
enableMethodologyGuides: boolean;
}
/**
* Framework Injector Implementation
* Injects framework system prompts into prompt execution context
*/
export class FrameworkInjector {
private frameworkManager: FrameworkManager;
private frameworkStateManager?: FrameworkStateManager; // NEW: For checking if framework system is enabled
private logger: Logger;
private config: FrameworkInjectionConfig;
constructor(
frameworkManager: FrameworkManager,
logger: Logger,
config: Partial<FrameworkInjectionConfig> = {},
frameworkStateManager?: FrameworkStateManager // NEW: Optional state manager
) {
this.frameworkManager = frameworkManager;
this.frameworkStateManager = frameworkStateManager;
this.logger = logger;
this.config = {
enableInjection: config.enableInjection ?? true,
injectionMethod: config.injectionMethod ?? 'system_prompt',
preserveOriginalSystemMessage: config.preserveOriginalSystemMessage ?? true,
includeFrameworkMetadata: config.includeFrameworkMetadata ?? true,
userPreferenceOverride: config.userPreferenceOverride,
enableMethodologyGuides: config.enableMethodologyGuides ?? true
};
}
/**
* Main framework injection method
* Enhances prompt with appropriate framework system prompt based on semantic analysis
*/
async injectFrameworkContext(
prompt: ConvertedPrompt,
semanticAnalysis: ContentAnalysisResult,
userFrameworkPreference?: string
): Promise<FrameworkInjectionResult> {
const startTime = Date.now();
try {
// Skip injection if disabled
if (!this.config.enableInjection) {
return this.createPassthroughResult(prompt);
}
// NEW: Skip injection if framework system is disabled
if (this.frameworkStateManager && !this.frameworkStateManager.isFrameworkSystemEnabled()) {
this.logger.debug(`Skipping framework injection - framework system is disabled: ${prompt.id}`);
return this.createPassthroughResult(prompt);
}
// Skip framework injection for basic "prompt" execution type
if (semanticAnalysis.executionType === "prompt") {
this.logger.debug(`Skipping framework injection for prompt execution: ${prompt.id}`);
return this.createPassthroughResult(prompt);
}
// Prepare framework selection criteria based on semantic analysis
const executionType = semanticAnalysis.executionType;
const selectionCriteria: FrameworkSelectionCriteria = {
executionType: executionType as "template" | "chain",
complexity: semanticAnalysis.complexity,
userPreference: (userFrameworkPreference || this.config.userPreferenceOverride) as any
};
// Generate framework execution context
const frameworkContext = this.frameworkManager.generateExecutionContext(
prompt,
selectionCriteria
);
// Create enhanced prompt with framework injection
const enhancedPrompt = this.performFrameworkInjection(
prompt,
frameworkContext,
semanticAnalysis
);
// Create injection result
const result: FrameworkInjectionResult = {
originalPrompt: prompt,
frameworkContext,
enhancedPrompt,
injectionMetadata: {
injectedAt: new Date(),
frameworkId: frameworkContext.selectedFramework.id,
injectionMethod: this.config.injectionMethod,
originalSystemMessage: prompt.systemMessage
}
};
const processingTime = Date.now() - startTime;
this.logger.debug(
`Framework injection completed: ${frameworkContext.selectedFramework.name} (${processingTime}ms)`
);
return result;
} catch (error) {
this.logger.error("Framework injection failed:", error);
return this.createPassthroughResult(prompt);
}
}
/**
* Quick framework system prompt injection for execution
*/
async injectSystemPrompt(
prompt: ConvertedPrompt,
semanticAnalysis: ContentAnalysisResult
): Promise<string> {
const result = await this.injectFrameworkContext(prompt, semanticAnalysis);
return result.enhancedPrompt.frameworkSystemPrompt || "";
}
/**
* Get framework guidelines for execution context
*/
async getFrameworkGuidelines(
prompt: ConvertedPrompt,
semanticAnalysis: ContentAnalysisResult
): Promise<string[]> {
const result = await this.injectFrameworkContext(prompt, semanticAnalysis);
return result.frameworkContext.executionGuidelines;
}
// Private implementation methods
/**
* Perform the actual framework injection based on configuration
*/
private performFrameworkInjection(
prompt: ConvertedPrompt,
frameworkContext: FrameworkExecutionContext,
semanticAnalysis: ContentAnalysisResult
): FrameworkInjectionResult['enhancedPrompt'] {
const framework = frameworkContext.selectedFramework;
const systemPrompt = frameworkContext.systemPrompt;
// Start with original prompt
const enhancedPrompt = { ...prompt } as FrameworkInjectionResult['enhancedPrompt'];
// Apply injection based on method
switch (this.config.injectionMethod) {
case 'system_prompt':
enhancedPrompt.frameworkSystemPrompt = systemPrompt;
// Combine with original system message if preservation is enabled
if (this.config.preserveOriginalSystemMessage && prompt.systemMessage) {
enhancedPrompt.systemMessage = `${systemPrompt}\n\n${prompt.systemMessage}`;
} else {
enhancedPrompt.systemMessage = systemPrompt;
}
break;
case 'user_prefix':
enhancedPrompt.frameworkSystemPrompt = systemPrompt;
// System prompt will be prepended to user message during execution
break;
case 'guidelines':
enhancedPrompt.frameworkGuidelines = frameworkContext.executionGuidelines;
// Guidelines will be applied during execution without modifying prompts
break;
}
// Apply methodology guide enhancements if enabled
if (this.config.enableMethodologyGuides) {
const methodologyGuide = this.getMethodologyGuide(framework.id);
if (methodologyGuide) {
try {
const methodologyEnhancement = methodologyGuide.enhanceWithMethodology(
prompt,
{ semanticAnalysis, frameworkContext }
);
enhancedPrompt.methodologyEnhancement = methodologyEnhancement;
// Apply methodology system prompt guidance if using system_prompt injection
if (this.config.injectionMethod === 'system_prompt' && methodologyEnhancement.systemPromptGuidance) {
const baseSystemPrompt = enhancedPrompt.systemMessage || '';
enhancedPrompt.systemMessage = `${baseSystemPrompt}\n\n${methodologyEnhancement.systemPromptGuidance}`;
}
this.logger.debug(`Methodology guide applied: ${methodologyGuide.methodology}`);
} catch (error) {
this.logger.warn(`Failed to apply methodology guide for ${framework.id}:`, error);
}
}
}
// Add framework metadata if enabled
if (this.config.includeFrameworkMetadata) {
enhancedPrompt.frameworkMetadata = {
selectedFramework: framework.name,
selectionReason: frameworkContext.metadata.selectionReason,
confidence: frameworkContext.metadata.confidence
};
}
return enhancedPrompt;
}
/**
* Get methodology guide for a specific framework
*/
private getMethodologyGuide(frameworkId: string): IMethodologyGuide | null {
try {
// Get methodology guide from framework manager
const guide = this.frameworkManager.getMethodologyGuide(frameworkId);
if (!guide) {
this.logger.debug(`No methodology guide available for framework: ${frameworkId}`);
return null;
}
return guide;
} catch (error) {
this.logger.warn(`Failed to get methodology guide for ${frameworkId}:`, error);
return null;
}
}
/**
* Create passthrough result when injection is disabled or fails
*/
private createPassthroughResult(prompt: ConvertedPrompt): FrameworkInjectionResult {
// Create minimal framework context for consistency
const defaultFramework = this.frameworkManager.listFrameworks(true)[0];
const minimalContext = this.frameworkManager.generateExecutionContext(
prompt,
{ executionType: "template", complexity: "low" }
);
return {
originalPrompt: prompt,
frameworkContext: minimalContext,
enhancedPrompt: prompt,
injectionMetadata: {
injectedAt: new Date(),
frameworkId: 'none',
injectionMethod: this.config.injectionMethod,
originalSystemMessage: prompt.systemMessage
}
};
}
/**
* Update injection configuration
*/
updateConfig(newConfig: Partial<FrameworkInjectionConfig>): void {
this.config = { ...this.config, ...newConfig };
this.logger.info("Framework injector configuration updated");
}
/**
* Get current injection configuration
*/
getConfig(): FrameworkInjectionConfig {
return { ...this.config };
}
}
/**
* Create and configure framework injector
*/
export async function createFrameworkInjector(
frameworkManager: FrameworkManager,
logger: Logger,
config?: Partial<FrameworkInjectionConfig>,
frameworkStateManager?: FrameworkStateManager // NEW: Optional state manager
): Promise<FrameworkInjector> {
return new FrameworkInjector(frameworkManager, logger, config, frameworkStateManager);
}
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/config-utils.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Configuration Utilities for Safe Config Management
*
* Provides atomic config operations with backup/rollback capabilities
* for secure configuration management in system_control tool.
*/
import { writeFile, readFile, copyFile, access } from "fs/promises";
import path from "path";
import { Config } from "../types/index.js";
import { ConfigManager } from "../config/index.js";
import { Logger } from "../logging/index.js";
/**
* Configuration write result
*/
export interface ConfigWriteResult {
success: boolean;
message: string;
backupPath?: string;
error?: string;
restartRequired?: boolean;
}
/**
* Configuration backup information
*/
export interface ConfigBackup {
backupPath: string;
timestamp: number;
originalConfig: Config;
}
/**
* Safe Configuration Writer
* Provides atomic config operations with automatic backup and rollback
*/
export class SafeConfigWriter {
private logger: Logger;
private configManager: ConfigManager;
private configPath: string;
constructor(logger: Logger, configManager: ConfigManager, configPath: string) {
this.logger = logger;
this.configManager = configManager;
this.configPath = configPath;
}
/**
* Safely update a configuration value with atomic operations
*/
async updateConfigValue(key: string, value: string): Promise<ConfigWriteResult> {
try {
// Step 1: Validate the operation
const validation = this.validateConfigUpdate(key, value);
if (!validation.valid) {
return {
success: false,
message: `Validation failed: ${validation.error}`,
error: validation.error
};
}
// Step 2: Create backup
const backup = await this.createConfigBackup();
this.logger.info(`Config backup created: ${backup.backupPath}`);
// Step 3: Load current config and apply changes
const currentConfig = this.configManager.getConfig();
const updatedConfig = this.applyConfigChange(currentConfig, key, validation.convertedValue);
// Step 4: Validate the entire updated configuration
const configValidation = this.validateFullConfig(updatedConfig);
if (!configValidation.valid) {
return {
success: false,
message: `Configuration validation failed: ${configValidation.error}`,
error: configValidation.error,
backupPath: backup.backupPath
};
}
// Step 5: Write the new configuration atomically
await this.writeConfigAtomic(updatedConfig);
// Step 6: Reload ConfigManager to use new config
await this.configManager.loadConfig();
return {
success: true,
message: `Configuration updated successfully: ${key} = ${value}`,
backupPath: backup.backupPath,
restartRequired: this.requiresRestart(key)
};
} catch (error) {
this.logger.error(`Failed to update config ${key}:`, error);
return {
success: false,
message: `Failed to update configuration: ${error}`,
error: String(error)
};
}
}
/**
* Create a timestamped backup of the current configuration
*/
private async createConfigBackup(): Promise<ConfigBackup> {
const timestamp = Date.now();
const backupPath = `${this.configPath}.backup.${timestamp}`;
try {
await copyFile(this.configPath, backupPath);
const originalConfig = this.configManager.getConfig();
this.logger.debug(`Config backup created: ${backupPath}`);
return {
backupPath,
timestamp,
originalConfig
};
} catch (error) {
this.logger.error(`Failed to create config backup:`, error);
throw new Error(`Backup creation failed: ${error}`);
}
}
/**
* Restore configuration from backup
*/
async restoreFromBackup(backupPath: string): Promise<ConfigWriteResult> {
try {
// Verify backup exists
await access(backupPath);
// Restore the backup
await copyFile(backupPath, this.configPath);
// Reload configuration
await this.configManager.loadConfig();
this.logger.info(`Configuration restored from backup: ${backupPath}`);
return {
success: true,
message: `Configuration successfully restored from backup`
};
} catch (error) {
this.logger.error(`Failed to restore from backup ${backupPath}:`, error);
return {
success: false,
message: `Failed to restore configuration: ${error}`,
error: String(error)
};
}
}
/**
* Write configuration file atomically (write to temp file, then rename)
*/
private async writeConfigAtomic(config: Config): Promise<void> {
const tempPath = `${this.configPath}.tmp`;
try {
// Write to temporary file first
const configJson = JSON.stringify(config, null, 2);
await writeFile(tempPath, configJson, 'utf8');
// Validate the written file can be parsed
const testContent = await readFile(tempPath, 'utf8');
JSON.parse(testContent); // Will throw if invalid
// Atomic rename (this is the atomic operation)
const fs = await import('fs');
fs.renameSync(tempPath, this.configPath);
this.logger.debug('Configuration written atomically');
} catch (error) {
// Clean up temp file if it exists
try {
const fs = await import('fs');
if (fs.existsSync(tempPath)) {
fs.unlinkSync(tempPath);
}
} catch (cleanupError) {
this.logger.warn(`Failed to clean up temp file ${tempPath}:`, cleanupError);
}
throw error;
}
}
/**
* Apply a configuration change to a config object
*/
private applyConfigChange(config: Config, key: string, value: any): Config {
// Deep clone the config to avoid mutations
const newConfig = JSON.parse(JSON.stringify(config));
// Apply the change using dot notation
const parts = key.split('.');
let current: any = newConfig;
// Navigate to the parent object
for (let i = 0; i < parts.length - 1; i++) {
const part = parts[i];
if (!current[part]) {
current[part] = {};
}
current = current[part];
}
// Set the final value
const finalKey = parts[parts.length - 1];
current[finalKey] = value;
return newConfig as Config;
}
/**
* Validate a configuration update
*/
private validateConfigUpdate(key: string, value: string): { valid: boolean; error?: string; convertedValue?: any } {
// Use the same validation logic as system-control
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" };
}
return { valid: true, convertedValue: port };
case 'server.name':
case 'server.version':
case 'logging.directory':
if (!value || value.trim().length === 0) {
return { valid: false, error: "Value cannot be empty" };
}
return { valid: true, convertedValue: value.trim() };
case 'transports.default':
if (!['stdio', 'sse'].includes(value)) {
return { valid: false, error: "Transport must be 'stdio' or 'sse'" };
}
return { valid: true, convertedValue: value };
case 'transports.stdio.enabled':
case 'transports.sse.enabled':
const boolValue = value.toLowerCase();
if (!['true', 'false'].includes(boolValue)) {
return { valid: false, error: "Value must be 'true' or 'false'" };
}
return { valid: true, convertedValue: boolValue === 'true' };
case 'logging.level':
if (!['debug', 'info', 'warn', 'error'].includes(value)) {
return { valid: false, error: "Log level must be: debug, info, warn, or error" };
}
return { valid: true, convertedValue: value };
case 'analysis.semanticAnalysis.llmIntegration.enabled':
const analysisEnabled = value.toLowerCase();
if (!['true', 'false'].includes(analysisEnabled)) {
return { valid: false, error: "Value must be 'true' or 'false'" };
}
return { valid: true, convertedValue: analysisEnabled === 'true' };
case 'analysis.semanticAnalysis.llmIntegration.model':
if (!value || value.trim().length === 0) {
return { valid: false, error: "Model name cannot be empty" };
}
return { valid: true, convertedValue: value.trim() };
case 'analysis.semanticAnalysis.llmIntegration.maxTokens':
const tokens = parseInt(value, 10);
if (isNaN(tokens) || tokens < 1 || tokens > 4000) {
return { valid: false, error: "Max tokens must be a number between 1-4000" };
}
return { valid: true, convertedValue: tokens };
case 'analysis.semanticAnalysis.llmIntegration.temperature':
const temp = parseFloat(value);
if (isNaN(temp) || temp < 0 || temp > 2) {
return { valid: false, error: "Temperature must be a number between 0-2" };
}
return { valid: true, convertedValue: temp };
default:
return { valid: false, error: `Unknown configuration key: ${key}` };
}
}
/**
* Validate the entire configuration object
*/
private validateFullConfig(config: Config): { valid: boolean; error?: string } {
try {
// Basic structure validation
if (!config.server || !config.transports) {
return { valid: false, error: "Missing required configuration sections" };
}
// Server validation
if (!config.server.name || !config.server.version || !config.server.port) {
return { valid: false, error: "Missing required server configuration" };
}
if (config.server.port < 1024 || config.server.port > 65535) {
return { valid: false, error: "Invalid server port range" };
}
// Transports validation
if (!['stdio', 'sse'].includes(config.transports.default)) {
return { valid: false, error: "Invalid default transport" };
}
if (typeof config.transports.stdio?.enabled !== 'boolean' ||
typeof config.transports.sse?.enabled !== 'boolean') {
return { valid: false, error: "Transport enabled flags must be boolean" };
}
// Logging validation (if present)
if (config.logging) {
if (!config.logging.directory || !config.logging.level) {
return { valid: false, error: "Missing required logging configuration" };
}
if (!['debug', 'info', 'warn', 'error'].includes(config.logging.level)) {
return { valid: false, error: "Invalid logging level" };
}
}
return { valid: true };
} catch (error) {
return { valid: false, error: `Configuration validation error: ${error}` };
}
}
/**
* Check if a configuration key requires server 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);
}
/**
* Get the configuration file path for debugging/info purposes
*/
getConfigPath(): string {
return this.configPath;
}
}
/**
* Create a SafeConfigWriter instance
*/
export function createSafeConfigWriter(
logger: Logger,
configManager: ConfigManager,
configPath: string
): SafeConfigWriter {
return new SafeConfigWriter(logger, configManager, configPath);
}
```
--------------------------------------------------------------------------------
/server/tests/performance/parsing-system-benchmark.test.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Simplified Performance Benchmark Tests for Parsing System
*
* Core performance tests focusing on essential benchmarks
*/
import { describe, test, expect, beforeEach, jest } from '@jest/globals';
import { performance } from 'perf_hooks';
import { Logger } from '../../src/logging/index.js';
import { PromptData } from '../../src/types/index.js';
import {
createParsingSystem,
type ExecutionContext
} from '../../src/execution/parsers/index.js';
// Mock logger for testing
const mockLogger: Logger = {
debug: jest.fn(),
info: jest.fn(),
warn: jest.fn(),
error: jest.fn()
} as any;
// Generate test prompts
function generateTestPrompts(count: number): PromptData[] {
const prompts: PromptData[] = [];
for (let i = 0; i < count; i++) {
prompts.push({
id: `test_prompt_${i}`,
name: `test_prompt_${i}`,
description: `Test prompt ${i}`,
userMessageTemplate: `Process {{content}} with format {{format}}`,
arguments: [
{
name: 'content',
description: 'Content to process',
required: true
},
{
name: 'format',
description: 'Output format',
required: false
}
],
category: 'test'
});
}
return prompts;
}
// Performance measurement utility
class PerformanceTimer {
private startTime: number = 0;
start(): void {
this.startTime = performance.now();
}
end(): number {
return performance.now() - this.startTime;
}
}
describe('Parsing System Performance Benchmarks', () => {
const TEST_PROMPTS = generateTestPrompts(100);
const BENCHMARK_ITERATIONS = 50;
describe('Command Parsing Performance', () => {
test('should parse commands efficiently', async () => {
const parsingSystem = createParsingSystem(mockLogger);
const timer = new PerformanceTimer();
const times: number[] = [];
for (let i = 0; i < BENCHMARK_ITERATIONS; i++) {
timer.start();
await parsingSystem.commandParser.parseCommand(
`>>test_prompt_${i % 10} hello world ${i}`,
TEST_PROMPTS.slice(0, 10)
);
times.push(timer.end());
}
const averageTime = times.reduce((a, b) => a + b, 0) / times.length;
const maxTime = Math.max(...times);
console.log(`Command Parsing Performance:
Average: ${averageTime.toFixed(2)}ms
Max: ${maxTime.toFixed(2)}ms`);
expect(averageTime).toBeLessThan(10); // Target: under 10ms per parse
expect(maxTime).toBeLessThan(50); // No single parse should take more than 50ms
});
test('should handle different command formats consistently', async () => {
const parsingSystem = createParsingSystem(mockLogger);
const formats = [
'>>test_prompt_1 hello world',
'/test_prompt_1 hello world',
'{"command": ">>test_prompt_1", "args": "hello world"}',
'test_prompt_1 {"content": "hello world"}'
];
const results: { format: string; time: number }[] = [];
for (const command of formats) {
const timer = new PerformanceTimer();
const times: number[] = [];
for (let i = 0; i < 10; i++) {
timer.start();
await parsingSystem.commandParser.parseCommand(command, TEST_PROMPTS.slice(0, 10));
times.push(timer.end());
}
const averageTime = times.reduce((a, b) => a + b, 0) / times.length;
results.push({ format: command.split(' ')[0], time: averageTime });
}
console.log('Command Format Performance:');
results.forEach(result => {
console.log(` ${result.format}: ${result.time.toFixed(2)}ms`);
});
// All formats should perform reasonably
results.forEach(result => {
expect(result.time).toBeLessThan(15);
});
// Performance should be consistent across formats
const maxTime = Math.max(...results.map(r => r.time));
const minTime = Math.min(...results.map(r => r.time));
expect(maxTime / minTime).toBeLessThan(2);
});
});
describe('Argument Processing Performance', () => {
test('should process arguments efficiently', async () => {
const parsingSystem = createParsingSystem(mockLogger);
const timer = new PerformanceTimer();
const times: number[] = [];
const context: ExecutionContext = {
conversationHistory: [
{ role: 'user', content: 'Previous message', timestamp: Date.now() }
],
environmentVars: process.env as Record<string, string>,
promptDefaults: { format: 'text' }
};
for (let i = 0; i < BENCHMARK_ITERATIONS; i++) {
const prompt = TEST_PROMPTS[i % TEST_PROMPTS.length];
timer.start();
await parsingSystem.argumentProcessor.processArguments(
`test content ${i}`,
prompt,
context
);
times.push(timer.end());
}
const averageTime = times.reduce((a, b) => a + b, 0) / times.length;
const maxTime = Math.max(...times);
console.log(`Argument Processing Performance:
Average: ${averageTime.toFixed(2)}ms
Max: ${maxTime.toFixed(2)}ms`);
expect(averageTime).toBeLessThan(5); // Target: under 5ms per process
expect(maxTime).toBeLessThan(20); // No single process should take more than 20ms
});
});
describe('Context Resolution Performance', () => {
test('should resolve context efficiently', async () => {
const parsingSystem = createParsingSystem(mockLogger);
const timer = new PerformanceTimer();
const times: number[] = [];
for (let i = 0; i < BENCHMARK_ITERATIONS; i++) {
timer.start();
await parsingSystem.contextResolver.resolveContext(`test_key_${i % 10}`);
times.push(timer.end());
}
const averageTime = times.reduce((a, b) => a + b, 0) / times.length;
const maxTime = Math.max(...times);
console.log(`Context Resolution Performance:
Average: ${averageTime.toFixed(2)}ms
Max: ${maxTime.toFixed(2)}ms`);
expect(averageTime).toBeLessThan(3); // Target: under 3ms per resolution
expect(maxTime).toBeLessThan(15); // No single resolution should take more than 15ms
});
test('should benefit from caching', async () => {
const parsingSystem = createParsingSystem(mockLogger);
const timer = new PerformanceTimer();
// First resolution (cache miss)
timer.start();
await parsingSystem.contextResolver.resolveContext('cached_key');
const firstTime = timer.end();
// Second resolution (cache hit)
timer.start();
await parsingSystem.contextResolver.resolveContext('cached_key');
const secondTime = timer.end();
console.log(`Caching Performance:
Cache miss: ${firstTime.toFixed(2)}ms
Cache hit: ${secondTime.toFixed(2)}ms
Improvement: ${((firstTime - secondTime) / firstTime * 100).toFixed(1)}%`);
expect(secondTime).toBeLessThan(firstTime * 0.5); // Cache should be at least 2x faster
expect(secondTime).toBeLessThan(1); // Cache hits should be very fast
});
});
describe('Memory Usage', () => {
test('should maintain reasonable memory usage', async () => {
const parsingSystem = createParsingSystem(mockLogger);
// Get initial memory usage
const initialMemory = process.memoryUsage();
// Perform intensive operations
for (let i = 0; i < 200; i++) {
await parsingSystem.commandParser.parseCommand(
`>>test_prompt_${i % 50} content ${i}`,
TEST_PROMPTS.slice(0, 50)
);
await parsingSystem.argumentProcessor.processArguments(
`content ${i}`,
TEST_PROMPTS[i % 50]
);
await parsingSystem.contextResolver.resolveContext(`key_${i % 25}`);
}
// Force garbage collection if available
if (global.gc) {
global.gc();
}
const finalMemory = process.memoryUsage();
const heapGrowth = (finalMemory.heapUsed - initialMemory.heapUsed) / 1024 / 1024; // MB
console.log(`Memory Usage:
Initial heap: ${(initialMemory.heapUsed / 1024 / 1024).toFixed(2)}MB
Final heap: ${(finalMemory.heapUsed / 1024 / 1024).toFixed(2)}MB
Growth: ${heapGrowth.toFixed(2)}MB`);
expect(heapGrowth).toBeLessThan(25); // Should not grow by more than 25MB
});
});
describe('Concurrent Operations', () => {
test('should handle concurrent parsing requests', async () => {
const parsingSystem = createParsingSystem(mockLogger);
const concurrentRequests = 10;
const timer = new PerformanceTimer();
timer.start();
const promises = Array(concurrentRequests).fill(null).map(async (_, i) => {
return parsingSystem.commandParser.parseCommand(
`>>test_prompt_${i % 5} concurrent test ${i}`,
TEST_PROMPTS.slice(0, 5)
);
});
await Promise.all(promises);
const totalTime = timer.end();
console.log(`Concurrent Parsing Performance:
${concurrentRequests} concurrent requests
Total time: ${totalTime.toFixed(2)}ms
Average per request: ${(totalTime / concurrentRequests).toFixed(2)}ms`);
expect(totalTime).toBeLessThan(250); // Should handle concurrency well
});
});
describe('Performance Regression Tests', () => {
test('should not regress from baseline performance', async () => {
// Baseline measurements (these would be actual measurements from previous versions)
const baselineCommandParsing = 15; // ms
const baselineArgumentProcessing = 8; // ms
const baselineContextResolution = 5; // ms
const parsingSystem = createParsingSystem(mockLogger);
const timer = new PerformanceTimer();
// Test command parsing performance
const commandTimes: number[] = [];
for (let i = 0; i < 10; i++) {
timer.start();
await parsingSystem.commandParser.parseCommand(
`>>test_prompt_${i % 5} regression test`,
TEST_PROMPTS.slice(0, 5)
);
commandTimes.push(timer.end());
}
const avgCommandTime = commandTimes.reduce((a, b) => a + b, 0) / commandTimes.length;
// Test argument processing performance
const argTimes: number[] = [];
for (let i = 0; i < 10; i++) {
timer.start();
await parsingSystem.argumentProcessor.processArguments(
'regression test content',
TEST_PROMPTS[0]
);
argTimes.push(timer.end());
}
const avgArgTime = argTimes.reduce((a, b) => a + b, 0) / argTimes.length;
// Test context resolution performance
const contextTimes: number[] = [];
for (let i = 0; i < 10; i++) {
timer.start();
await parsingSystem.contextResolver.resolveContext('regression_test');
contextTimes.push(timer.end());
}
const avgContextTime = contextTimes.reduce((a, b) => a + b, 0) / contextTimes.length;
console.log(`Performance Regression Check:
Command Parsing - Baseline: ${baselineCommandParsing}ms, Current: ${avgCommandTime.toFixed(2)}ms
Argument Processing - Baseline: ${baselineArgumentProcessing}ms, Current: ${avgArgTime.toFixed(2)}ms
Context Resolution - Baseline: ${baselineContextResolution}ms, Current: ${avgContextTime.toFixed(2)}ms`);
// Allow for slight performance variations but no major regressions
expect(avgCommandTime).toBeLessThan(baselineCommandParsing * 1.2);
expect(avgArgTime).toBeLessThan(baselineArgumentProcessing * 1.2);
expect(avgContextTime).toBeLessThan(baselineContextResolution * 1.2);
});
});
});
```
--------------------------------------------------------------------------------
/docs/mcp-tool-usage-guide.md:
--------------------------------------------------------------------------------
```markdown
# MCP Tool Usage Guide
## Overview
This guide explains the **correct way** to interact with the Claude Prompts MCP server. The server provides structured MCP tools that should be used instead of direct file manipulation.
## ❌ Wrong Approach (What NOT to do)
**Never use these tools directly:**
- `Update()` - Direct file modification
- `Write()` - Creating files directly
- `Edit()` - Direct file editing
- `MultiEdit()` - Direct file operations
- Direct filesystem manipulation via `Bash` commands
**Example of INCORRECT usage from logFail.txt:**
```
● Update(~/Applications/claude-prompts-mcp/server/prompts/chains/notes_modular/chain.json)
● Write(~/Applications/claude-prompts-mcp/server/prompts/chains/notes_modular/steps/step_5.md)
● Write(~/Applications/claude-prompts-mcp/server/prompts/analysis/notes_step_5.md)
```
This bypasses the MCP system and leads to:
- MCP protocol violations
- Missing structured content errors
- Data inconsistency
- Broken hot-reloading
- Registry desynchronization
## ✅ Correct Approach (MCP Tools)
### 1. Prompt Manager Tool
The `prompt_manager` tool is your primary interface for all prompt operations:
#### Available Actions:
- `create` - Create new prompts (auto-detects type)
- `create_prompt` - Create basic variable-substitution prompts
- `create_template` - Create framework-aware templates
- `update` - Update existing prompts
- `delete` - Delete prompts with safety checks
- `modify` - Modify specific sections of prompts
- `reload` - Hot-reload all prompts
- `list` - List and search prompts
- `analyze_type` - Analyze prompt execution type
- `migrate_type` - Convert between prompt/template types
### 2. System Control Tool
The `system_control` tool manages server state and frameworks:
#### Available Actions:
- `status` - Get system status and health
- `switch_framework` - Change active methodology framework
- `list_frameworks` - List available frameworks
- `analytics` - Get execution analytics
- `config` - Configuration management
- `restart` - Server restart (with confirmation)
### 3. Prompt Engine Tool
The `prompt_engine` tool executes prompts and chains:
#### Command Formats:
- `>>prompt_name arguments` - Execute simple prompts
- `chain://chain_name` - Execute chains via URI
- `scaffold chain_name template:custom` - Create new chains
- `convert source_prompt` - Convert prompts to chains
## Correct Chain Modification Workflow
### Scenario: Adding a vault search step to notes chain
**The RIGHT way to do this:**
```bash
# 1. First, check what exists
prompt_manager(action: "list", filter: "notes")
# 2. Check if vault_related_notes_finder exists
prompt_manager(action: "list", filter: "vault")
# 3. If the vault finder doesn't exist, create it
prompt_manager(action: "create", id: "vault_related_notes_finder",
name: "Vault Related Notes Finder",
category: "content_processing",
description: "Searches vault for relevant related notes",
user_message_template: "Find related notes in {{vault_path}} for: {{note_topic}}")
# 4. Update the notes chain to include the new step
prompt_manager(action: "update", id: "notes_modular",
chain_steps: [
// existing steps...
{
"id": "step_4",
"name": "Vault Related Notes Search",
"promptId": "vault_related_notes_finder",
"order": 3,
"dependencies": ["step_3"],
"inputMapping": {
"note_topic": "content",
"vault_path": "/path/to/vault"
},
"outputMapping": {
"result": "related_notes"
}
},
// updated final step...
])
# 5. Reload to apply changes
prompt_manager(action: "reload")
# 6. Test the updated chain
prompt_engine(command: ">>notes_modular content:'Test content'")
```
## Common Usage Patterns
### Pattern 1: Creating New Prompts
```bash
# Basic prompt (simple variable substitution)
prompt_manager(action: "create_prompt",
id: "my_prompt",
name: "My Simple Prompt",
user_message_template: "Analyze: {{content}}")
# Framework-aware template
prompt_manager(action: "create_template",
id: "my_template",
name: "My Smart Template",
user_message_template: "Using systematic methodology: {{input}}")
```
### Pattern 2: Modifying Existing Prompts
```bash
# Update entire prompt
prompt_manager(action: "update", id: "existing_prompt",
name: "Updated Name",
user_message_template: "New template: {{input}}")
# Modify specific section
prompt_manager(action: "modify", id: "existing_prompt",
section_name: "user_message_template",
new_content: "Modified template: {{input}}")
```
### Pattern 3: Working with Chains
```bash
# List chains
prompt_manager(action: "list", filter: "type:chain")
# Execute chain
prompt_engine(command: ">>chain_name input:'data'")
# Create new chain using scaffolding
prompt_engine(command: "scaffold new_chain template:custom name:'My Chain'")
```
### Pattern 4: System Management
```bash
# Check system status
system_control(action: "status")
# Switch framework methodology
system_control(action: "switch_framework", framework: "CAGEERF",
reason: "Better for complex analysis")
# Get analytics
system_control(action: "analytics", include_history: true)
```
### Pattern 5: Quality Gates (Simplified)
Use the simplified hybrid interface to combine built-in gates with quick custom checks.
#### Discover Available Gates
```javascript
// List all configured gates
system_control({
action: "gates",
operation: "list"
})
```
#### Basic Usage: Built-in Gates
```javascript
prompt_engine({
command: ">>code_review code='...'",
quality_gates: ["gate-name-1", "gate-name-2"],
gate_mode: "enforce"
})
```
#### Advanced: Custom Checks
```javascript
prompt_engine({
command: ">>my_prompt",
quality_gates: ["gate-name"],
custom_checks: [
{ name: "production-ready", description: "Include error handling and logging" }
],
gate_mode: "enforce"
})
```
#### Gate Modes
- **enforce**: Validates output, retries on failure with improvement hints (default when gates provided)
- **advise**: Provides guidance without blocking execution
- **report**: Runs validation once and includes pass/fail status in the response
> Need full control? `temporary_gates` remains available for advanced scenarios, but prefer `quality_gates` and `custom_checks` for most workflows.
## Advanced Search and Discovery
The prompt_manager supports advanced filtering:
```bash
# Search by category
prompt_manager(action: "list", filter: "category:analysis")
# Search by type
prompt_manager(action: "list", filter: "type:chain")
# Search by intent
prompt_manager(action: "list", filter: "intent:debugging")
# Combined filters
prompt_manager(action: "list", filter: "category:code type:template confidence:>80")
# Text search
prompt_manager(action: "list", filter: "notes vault")
```
## Error Recovery
If you encounter MCP protocol errors:
1. **Check tool response structure**:
- All tools return structured responses with `content` and `structuredContent`
- Error responses include proper error metadata
2. **Use reload to fix state issues**:
```bash
prompt_manager(action: "reload")
```
3. **Check system health**:
```bash
system_control(action: "diagnostics")
```
4. **Restart if needed**:
```bash
system_control(action: "restart", confirm: true, reason: "Fix protocol errors")
```
## Best Practices
### ✅ DO:
- Always use MCP tools for prompt/chain management
- Use `prompt_manager(action: "list")` to explore available prompts
- Test changes with `prompt_manager(action: "reload")`
- Use structured search filters to find relevant prompts
- Check system status with `system_control(action: "status")`
### ❌ DON'T:
- Never use direct file manipulation (Update, Write, Edit, MultiEdit)
- Don't bypass the MCP tool interface
- Don't create files directly in the prompts directory
- Don't modify JSON files manually
- Don't skip the reload step after changes
## Troubleshooting
### Common Parameter Mistakes
#### ❌ "Missing required fields: id, name, description, user_message_template"
**Problem**: Trying to create a prompt without all required parameters.
**Solution**: All create actions require 4 essential parameters:
```bash
prompt_manager(
action: "create",
id: "unique_identifier", # ⚠️ REQUIRED
name: "Human Readable Name", # ⚠️ REQUIRED
description: "What it does", # ⚠️ REQUIRED
user_message_template: "{{input}}" # ⚠️ REQUIRED
)
```
**Common variations**:
- ❌ `userMessageTemplate` → ✅ `user_message_template` (snake_case)
- ❌ Missing `id` → ✅ Always include unique identifier
- ❌ Empty string → ✅ Provide meaningful content
#### ❌ "Missing required fields: id"
**Problem**: Trying to update/delete/modify without specifying which prompt.
**Solution**: Most operations need the `id` parameter:
```bash
# Update
prompt_manager(action: "update", id: "my_prompt", description: "New description")
# Delete
prompt_manager(action: "delete", id: "my_prompt")
# Analyze
prompt_manager(action: "analyze_type", id: "my_prompt")
```
#### ❌ "Prompt ID must contain only alphanumeric characters, underscores, and hyphens"
**Problem**: Using invalid characters in prompt ID.
**Solution**: IDs must match pattern `^[a-zA-Z0-9_-]+$`:
```bash
# ❌ Bad IDs
id: "my prompt" # spaces not allowed
id: "my.prompt" # dots not allowed
id: "my/prompt" # slashes not allowed
# ✅ Good IDs
id: "my_prompt" # underscores OK
id: "my-prompt" # hyphens OK
id: "MyPrompt123" # alphanumeric OK
```
### Parameter Quick Reference
| Action | Required Parameters | Optional Parameters |
|--------|-------------------|-------------------|
| `create` | `id`, `name`, `description`, `user_message_template` | `category`, `system_message`, `arguments` |
| `create_prompt` | `id`, `name`, `description`, `user_message_template` | `category`, `system_message`, `arguments` |
| `create_template` | `id`, `name`, `description`, `user_message_template` | `category`, `system_message`, `arguments` |
| `create_with_gates` | `id`, `name`, `description`, `user_message_template`, `gate_configuration` OR `suggested_gates` | `category`, `system_message`, `arguments` |
| `update` | `id` | Any field to update |
| `delete` | `id` | - |
| `modify` | `id`, `section_name`, `new_content` | - |
| `analyze_type` | `id` | - |
| `migrate_type` | `id`, `target_type` | - |
| `analyze_gates` | `id` | - |
| `update_gates` | `id`, `gate_configuration` | - |
| `add_temporary_gates` | `id`, `temporary_gates` | `gate_scope`, `inherit_chain_gates` |
| `suggest_temporary_gates` | `execution_context` | - |
| `reload` | - | `full_restart`, `reason` |
| `list` | - | `search_query` |
### MCP Protocol Errors
#### "MCP error -32602: Tool has output schema but no structured content"
This indicates a tool isn't returning properly structured responses. This has been fixed in recent versions, but if encountered:
- Update to the latest server version
- Use the MCP tools instead of direct file operations
#### "Resource not found" errors
- Use `prompt_manager(action: "list")` to see available prompts
- Check that the prompt ID exists before trying to modify it
- Use reload to refresh the registry
### Chain Execution Failures
- Validate chain structure with `prompt_manager(action: "list", filter: "type:chain")`
- Check step dependencies and input/output mappings
- Use `system_control(action: "diagnostics")` for debugging
## Summary
The MCP server provides a structured, consistent interface for managing prompts and chains. Always use the MCP tools (`prompt_manager`, `system_control`, `prompt_engine`) instead of direct file manipulation. This ensures data consistency, proper error handling, and maintains the MCP protocol compliance.
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-engine/utils/validation.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Engine Validator - Handles engine-specific validation
*
* Extracted from ConsolidatedPromptEngine to provide focused
* validation capabilities with clear separation of concerns.
*/
import { createLogger } from "../../../logging/index.js";
import { ConvertedPrompt } from "../../../types/index.js";
import { LightweightGateSystem } from "../../../gates/core/index.js";
const logger = createLogger({
logFile: '/tmp/engine-validator.log',
transport: 'stdio',
enableDebug: false,
configuredLevel: 'info'
});
export interface ValidationResult {
isValid: boolean;
errors: string[];
warnings: string[];
score: number;
}
export interface GateValidationResult {
passed: boolean;
results: Array<{
gate: string;
passed: boolean;
message: string;
score?: number;
}>;
}
/**
* EngineValidator handles all engine-specific validation
*
* This class provides:
* - Prompt validation and quality checking
* - Gate validation coordination
* - Execution readiness assessment
* - Quality scoring and recommendations
*/
export class EngineValidator {
private gateSystem?: LightweightGateSystem;
constructor(gateSystem?: LightweightGateSystem) {
this.gateSystem = gateSystem;
}
/**
* Validate prompt for execution readiness
*/
public validatePrompt(
convertedPrompt: ConvertedPrompt,
promptArgs: Record<string, any> = {}
): ValidationResult {
try {
logger.debug('🔍 [EngineValidator] Validating prompt', {
promptId: convertedPrompt.id,
hasArgs: Object.keys(promptArgs).length > 0
});
const errors: string[] = [];
const warnings: string[] = [];
let score = 100;
// Basic prompt validation
if (!convertedPrompt.id) {
errors.push("Prompt ID is missing");
score -= 50;
}
if (!convertedPrompt.userMessageTemplate || convertedPrompt.userMessageTemplate.trim().length === 0) {
errors.push("Prompt content is empty");
score -= 50;
}
// Content quality validation
const contentValidation = this.validateContent(convertedPrompt.userMessageTemplate);
errors.push(...contentValidation.errors);
warnings.push(...contentValidation.warnings);
score = Math.min(score, contentValidation.score);
// Arguments validation
const argsValidation = this.validateArguments(convertedPrompt, promptArgs);
errors.push(...argsValidation.errors);
warnings.push(...argsValidation.warnings);
score = Math.min(score, argsValidation.score);
const isValid = errors.length === 0;
logger.debug('✅ [EngineValidator] Prompt validation completed', {
promptId: convertedPrompt.id,
isValid,
score,
errorsCount: errors.length,
warningsCount: warnings.length
});
return { isValid, errors, warnings, score };
} catch (error) {
logger.error('❌ [EngineValidator] Prompt validation failed', {
promptId: convertedPrompt.id,
error: error instanceof Error ? error.message : String(error)
});
return {
isValid: false,
errors: [`Validation error: ${error instanceof Error ? error.message : String(error)}`],
warnings: [],
score: 0
};
}
}
/**
* Validate prompt content quality
*/
private validateContent(content: string | undefined): ValidationResult {
const errors: string[] = [];
const warnings: string[] = [];
let score = 100;
// Handle undefined content
if (!content) {
errors.push("Content is undefined or missing");
return { isValid: false, errors, warnings, score: 0 };
}
// Length validation
if (content.length < 10) {
errors.push("Content is too short (minimum 10 characters)");
score -= 30;
}
if (content.length > 50000) {
warnings.push("Content is very long, may impact performance");
score -= 10;
}
// Template syntax validation
const templateErrors = this.validateTemplateSyntax(content);
if (templateErrors.length > 0) {
errors.push(...templateErrors);
score -= 20;
}
// Content structure validation
const structureWarnings = this.validateContentStructure(content);
warnings.push(...structureWarnings);
if (structureWarnings.length > 0) {
score -= 5;
}
return { isValid: errors.length === 0, errors, warnings, score };
}
/**
* Validate template syntax
*/
private validateTemplateSyntax(content: string): string[] {
const errors: string[] = [];
// Check for unmatched braces
const openBraces = (content.match(/\{\{/g) || []).length;
const closeBraces = (content.match(/\}\}/g) || []).length;
if (openBraces !== closeBraces) {
errors.push(`Unmatched template braces: ${openBraces} opening, ${closeBraces} closing`);
}
// Check for unmatched control structures
const ifTags = (content.match(/\{%\s*if\s/g) || []).length;
const endifTags = (content.match(/\{%\s*endif\s*%\}/g) || []).length;
if (ifTags !== endifTags) {
errors.push(`Unmatched if/endif tags: ${ifTags} if, ${endifTags} endif`);
}
const forTags = (content.match(/\{%\s*for\s/g) || []).length;
const endforTags = (content.match(/\{%\s*endfor\s*%\}/g) || []).length;
if (forTags !== endforTags) {
errors.push(`Unmatched for/endfor tags: ${forTags} for, ${endforTags} endfor`);
}
return errors;
}
/**
* Validate content structure
*/
private validateContentStructure(content: string): string[] {
const warnings: string[] = [];
// Check for overly complex nesting
const maxNesting = this.calculateMaxNesting(content);
if (maxNesting > 3) {
warnings.push(`Deep template nesting detected (${maxNesting} levels), consider simplifying`);
}
// Check for potential infinite loops
if (content.includes('{% for') && !content.includes('{% endfor %}')) {
warnings.push("Potential incomplete for loop detected");
}
// Check for missing variable fallbacks
const variables = content.match(/\{\{\s*([^}]+)\s*\}\}/g) || [];
for (const variable of variables) {
if (!variable.includes('|') && !variable.includes('default')) {
warnings.push(`Variable ${variable} has no fallback value`);
}
}
return warnings;
}
/**
* Calculate maximum nesting level
*/
private calculateMaxNesting(content: string): number {
let maxNesting = 0;
let currentNesting = 0;
const lines = content.split('\n');
for (const line of lines) {
if (line.includes('{% for') || line.includes('{% if')) {
currentNesting++;
maxNesting = Math.max(maxNesting, currentNesting);
} else if (line.includes('{% endfor') || line.includes('{% endif')) {
currentNesting = Math.max(0, currentNesting - 1);
}
}
return maxNesting;
}
/**
* Validate arguments against prompt requirements
*/
private validateArguments(
convertedPrompt: ConvertedPrompt,
promptArgs: Record<string, any>
): ValidationResult {
const errors: string[] = [];
const warnings: string[] = [];
let score = 100;
if (!convertedPrompt.arguments || convertedPrompt.arguments.length === 0) {
return { isValid: true, errors, warnings, score };
}
// Check required arguments
for (const arg of convertedPrompt.arguments) {
if (arg.required && !promptArgs.hasOwnProperty(arg.name)) {
errors.push(`Missing required argument: ${arg.name}`);
score -= 20;
}
}
// Check argument types
for (const arg of convertedPrompt.arguments) {
if (promptArgs.hasOwnProperty(arg.name)) {
const value = promptArgs[arg.name];
if (!this.isValidArgumentType(value, arg.type || 'string')) {
errors.push(`Argument '${arg.name}' should be of type '${arg.type}', got '${typeof value}'`);
score -= 10;
}
}
}
// Check for unused arguments
const expectedArgs = convertedPrompt.arguments.map((arg: any) => arg.name);
for (const argName of Object.keys(promptArgs)) {
if (!expectedArgs.includes(argName)) {
warnings.push(`Unexpected argument provided: ${argName}`);
score -= 2;
}
}
return { isValid: errors.length === 0, errors, warnings, score };
}
/**
* Validate argument type
*/
private isValidArgumentType(value: any, expectedType: string): boolean {
switch (expectedType.toLowerCase()) {
case 'string':
return typeof value === 'string';
case 'number':
return typeof value === 'number' && !isNaN(value);
case 'boolean':
return typeof value === 'boolean';
case 'array':
return Array.isArray(value);
case 'object':
return typeof value === 'object' && value !== null && !Array.isArray(value);
default:
return true; // Unknown types are considered valid
}
}
/**
* Validate execution with gates
*/
public async validateWithGates(
convertedPrompt: ConvertedPrompt,
promptArgs: Record<string, any>,
suggestedGates: string[] = [],
processedContent?: string
): Promise<GateValidationResult> {
try {
logger.debug('🚪 [EngineValidator] Validating with gates', {
promptId: convertedPrompt.id,
gatesCount: suggestedGates.length,
hasProcessedContent: !!processedContent
});
if (!this.gateSystem || suggestedGates.length === 0) {
return { passed: true, results: [] };
}
const results: Array<{ gate: string; passed: boolean; message: string; score?: number }> = [];
let allPassed = true;
// FIXED: Use processed content for validation, not raw template
const contentToValidate = processedContent || convertedPrompt.userMessageTemplate || '';
for (const gateName of suggestedGates) {
try {
const gateResults = await this.gateSystem.validateContent(
[gateName],
contentToValidate,
{
promptId: convertedPrompt.id,
stepId: gateName,
attemptNumber: 1,
previousAttempts: []
}
);
const gateResult = gateResults[0] || { valid: false, errors: [{ field: 'gate', message: 'Gate validation failed', code: 'VALIDATION_ERROR' }] };
results.push({
gate: gateName,
passed: gateResult.valid || gateResult.passed || false,
message: gateResult.errors?.length ? gateResult.errors[0].message : (gateResult.valid ? 'Gate passed' : 'Gate failed'),
score: 85 // Default validation score
});
if (!gateResult.valid && !gateResult.passed) {
allPassed = false;
}
} catch (error) {
results.push({
gate: gateName,
passed: false,
message: `Gate validation error: ${error instanceof Error ? error.message : String(error)}`
});
allPassed = false;
}
}
logger.debug('✅ [EngineValidator] Gate validation completed', {
promptId: convertedPrompt.id,
allPassed,
resultsCount: results.length
});
return { passed: allPassed, results };
} catch (error) {
logger.error('❌ [EngineValidator] Gate validation failed', {
promptId: convertedPrompt.id,
error: error instanceof Error ? error.message : String(error)
});
return {
passed: false,
results: [{
gate: 'system',
passed: false,
message: `Gate system error: ${error instanceof Error ? error.message : String(error)}`
}]
};
}
}
}
```
--------------------------------------------------------------------------------
/server/tests/enhanced-validation/environment-validation/environment-test-suite.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Environment Parity Validation Test Suite
*
* Tests environment consistency validation to prevent local vs CI environment failures
*/
async function runEnvironmentValidationTests() {
try {
console.log('🌍 Running Environment Parity Validation Tests...');
console.log('🎯 Preventing local vs CI environment failures\n');
const results = {
environmentChecker: false,
nodeVersionValidation: false,
environmentVariables: false,
filesystemBehavior: false,
dependencyValidation: false,
totalTests: 0,
passedTests: 0
};
// Test 1: Environment Checker Creation
console.log('🔧 Test 1: Environment Parity Checker Functionality');
results.totalTests++;
try {
const { createEnvironmentParityChecker } = await import('./environment-parity-checker.js');
const { MockLogger } = await import('../../helpers/test-helpers.js');
const logger = new MockLogger();
const checker = createEnvironmentParityChecker(logger);
if (checker && typeof checker.generateParityReport === 'function') {
console.log(' ✅ EnvironmentParityChecker created successfully');
console.log(' ✅ All required methods available');
results.environmentChecker = true;
results.passedTests++;
} else {
console.log(' ❌ EnvironmentParityChecker missing required methods');
}
} catch (error) {
console.log(` ❌ Environment checker creation failed: ${error.message}`);
}
// Test 2: Node.js Version Validation
console.log('\n📦 Test 2: Node.js Version Validation');
results.totalTests++;
try {
const { createEnvironmentParityChecker } = await import('./environment-parity-checker.js');
const { MockLogger } = await import('../../helpers/test-helpers.js');
const logger = new MockLogger();
const checker = createEnvironmentParityChecker(logger);
const nodeReport = await checker.validateNodeVersion();
if (nodeReport && typeof nodeReport.valid === 'boolean') {
console.log(' ✅ Node.js version validation completed');
console.log(` 📊 Current version: ${nodeReport.currentVersion}`);
console.log(` 📊 Required version: ${nodeReport.requiredVersion}`);
console.log(` 📊 Valid: ${nodeReport.valid ? 'Yes' : 'No'}`);
if (nodeReport.details) {
console.log(` 📋 Details: ${nodeReport.details}`);
}
if (nodeReport.warning) {
console.log(` ⚠️ Warning: ${nodeReport.warning}`);
}
if (nodeReport.recommendation) {
console.log(` 💡 Recommendation: ${nodeReport.recommendation}`);
}
results.nodeVersionValidation = true;
results.passedTests++;
} else {
console.log(' ❌ Node.js version validation returned invalid result');
}
} catch (error) {
console.log(` ❌ Node.js version validation failed: ${error.message}`);
}
// Test 3: Environment Variables Validation
console.log('\n🔐 Test 3: Environment Variables Validation');
results.totalTests++;
try {
const { createEnvironmentParityChecker } = await import('./environment-parity-checker.js');
const { MockLogger } = await import('../../helpers/test-helpers.js');
const logger = new MockLogger();
const checker = createEnvironmentParityChecker(logger);
const envReport = await checker.validateEnvironmentVariables();
if (envReport && typeof envReport.valid === 'boolean') {
console.log(' ✅ Environment variables validation completed');
console.log(` 📊 Valid: ${envReport.valid ? 'Yes' : 'No'}`);
console.log(` 📊 CI Environment: ${envReport.ciEnvironment.detected ? 'Yes' : 'No'}`);
console.log(` 📊 Platform: ${envReport.platform.os} (${envReport.platform.arch})`);
if (envReport.platform.isWSL) {
console.log(' 🐧 WSL environment detected');
}
if (envReport.missing.length > 0) {
console.log(` ⚠️ Missing variables: ${envReport.missing.join(', ')}`);
}
if (envReport.recommendations.length > 0) {
console.log(' 💡 Recommendations provided for environment setup');
}
results.environmentVariables = true;
results.passedTests++;
} else {
console.log(' ❌ Environment variables validation returned invalid result');
}
} catch (error) {
console.log(` ❌ Environment variables validation failed: ${error.message}`);
}
// Test 4: Filesystem Behavior Validation
console.log('\n📁 Test 4: Filesystem Behavior Validation');
results.totalTests++;
try {
const { createEnvironmentParityChecker } = await import('./environment-parity-checker.js');
const { MockLogger } = await import('../../helpers/test-helpers.js');
const logger = new MockLogger();
const checker = createEnvironmentParityChecker(logger);
const fsReport = await checker.validateFilesystemBehavior();
if (fsReport && typeof fsReport.valid === 'boolean') {
console.log(' ✅ Filesystem behavior validation completed');
console.log(` 📊 Platform: ${fsReport.platform}`);
console.log(` 📊 Path separator: "${fsReport.pathSeparator}"`);
console.log(` 📊 Case sensitive: ${fsReport.caseSensitive ? 'Yes' : 'No'}`);
console.log(` 📊 Long paths: ${fsReport.supportsLongPaths ? 'Supported' : 'Limited'}`);
console.log(` 📊 Symlinks: ${fsReport.supportsSymlinks ? 'Supported' : 'Not available'}`);
if (fsReport.issues.length > 0) {
console.log(` ⚠️ Issues: ${fsReport.issues.join(', ')}`);
}
results.filesystemBehavior = true;
results.passedTests++;
} else {
console.log(' ❌ Filesystem behavior validation returned invalid result');
if (fsReport.error) {
console.log(` Error: ${fsReport.error}`);
}
}
} catch (error) {
console.log(` ❌ Filesystem behavior validation failed: ${error.message}`);
}
// Test 5: Package Dependencies Validation
console.log('\n📋 Test 5: Package Dependencies Validation');
results.totalTests++;
try {
const { createEnvironmentParityChecker } = await import('./environment-parity-checker.js');
const { MockLogger } = await import('../../helpers/test-helpers.js');
const logger = new MockLogger();
const checker = createEnvironmentParityChecker(logger);
const depReport = await checker.validatePackageDependencies();
if (depReport && typeof depReport.valid === 'boolean') {
console.log(' ✅ Package dependencies validation completed');
console.log(` 📊 package.json exists: ${depReport.packageJsonExists ? 'Yes' : 'No'}`);
console.log(` 📊 package-lock.json exists: ${depReport.lockfileExists ? 'Yes' : 'No'}`);
console.log(` 📊 Dependencies: ${depReport.dependencies ? depReport.dependencies.length : 0}`);
console.log(` 📊 Dev dependencies: ${depReport.devDependencies ? depReport.devDependencies.length : 0}`);
console.log(` 📊 Valid: ${depReport.valid ? 'Yes' : 'No'}`);
if (depReport.issues && depReport.issues.length > 0) {
console.log(` ⚠️ Issues: ${depReport.issues.join(', ')}`);
}
if (depReport.recommendations && depReport.recommendations.length > 0) {
console.log(' 💡 Recommendations provided for dependency management');
}
results.dependencyValidation = true;
results.passedTests++;
} else {
console.log(' ❌ Package dependencies validation returned invalid result');
if (depReport.error) {
console.log(` Error: ${depReport.error}`);
}
}
} catch (error) {
console.log(` ❌ Package dependencies validation failed: ${error.message}`);
}
// Test 6: Comprehensive Environment Report
console.log('\n📊 Test 6: Comprehensive Environment Report');
results.totalTests++;
try {
const { createEnvironmentParityChecker } = await import('./environment-parity-checker.js');
const { MockLogger } = await import('../../helpers/test-helpers.js');
const logger = new MockLogger();
const checker = createEnvironmentParityChecker(logger);
const fullReport = await checker.generateParityReport();
if (fullReport && fullReport.overall) {
console.log(' ✅ Comprehensive environment report generated');
console.log(` 📊 Overall valid: ${fullReport.overall.valid ? 'Yes' : 'No'}`);
console.log(` 📊 Environment: ${fullReport.overall.environment}`);
console.log(` 📊 Platform: ${fullReport.overall.platform}`);
console.log(` 📊 Node version: ${fullReport.overall.nodeVersion}`);
console.log(` ⏱️ Validation time: ${fullReport.validationTime}ms`);
if (fullReport.recommendations.length > 0) {
console.log(` 💡 Total recommendations: ${fullReport.recommendations.length}`);
}
results.passedTests++;
} else {
console.log(' ❌ Comprehensive environment report generation failed');
}
} catch (error) {
console.log(` ❌ Comprehensive environment report failed: ${error.message}`);
}
// Summary
console.log('\n' + '='.repeat(60));
console.log('📊 ENVIRONMENT PARITY VALIDATION RESULTS');
console.log('='.repeat(60));
console.log(`📈 Tests Passed: ${results.passedTests}/${results.totalTests}`);
console.log(`📊 Success Rate: ${((results.passedTests / results.totalTests) * 100).toFixed(1)}%`);
console.log('');
console.log('🔧 Component Status:');
console.log(` Environment Checker: ${results.environmentChecker ? '✅' : '❌'}`);
console.log(` Node Version Validation: ${results.nodeVersionValidation ? '✅' : '❌'}`);
console.log(` Environment Variables: ${results.environmentVariables ? '✅' : '❌'}`);
console.log(` Filesystem Behavior: ${results.filesystemBehavior ? '✅' : '❌'}`);
console.log(` Dependency Validation: ${results.dependencyValidation ? '✅' : '❌'}`);
if (results.passedTests >= 5) { // Allow for some tolerance
console.log('\n🎉 Environment parity validation system is working!');
console.log('✅ Local vs CI environment differences can be detected early');
console.log('✅ Environment-specific failures should be prevented');
return true;
} else {
console.log('\n❌ Environment parity validation system has issues');
console.log('⚠️ Environment differences may still cause CI failures');
return false;
}
} catch (error) {
console.error('❌ Environment validation test execution failed:', error.message);
console.error('Stack trace:', error.stack);
return false;
}
}
// Handle process cleanup gracefully
process.on('uncaughtException', (error) => {
console.error('❌ Uncaught exception in environment validation tests:', error.message);
});
process.on('unhandledRejection', (reason) => {
console.error('❌ Unhandled rejection in environment validation tests:', reason);
});
// Run the tests with natural completion
if (import.meta.url === `file://${process.argv[1]}`) {
runEnvironmentValidationTests().then(success => {
if (success) {
console.log('\n🎯 Environment validation completed successfully!');
} else {
console.log('\n⚠️ Environment validation completed with some issues');
}
// Natural completion - no process.exit() calls
}).catch(error => {
console.error('❌ Test execution failed:', error);
// Natural completion even on error - no process.exit() calls
});
}
```
--------------------------------------------------------------------------------
/server/tests/scripts/unit-unified-parsing.js:
--------------------------------------------------------------------------------
```javascript
#!/usr/bin/env node
/**
* Unified Parsing System Unit Tests - Node.js Script Version
* Core functionality tests focusing on essential parsing behavior
*/
async function runUnifiedParsingTests() {
try {
console.log('🧪 Running Unified Parsing System unit tests...');
console.log('📋 Testing command parsing, argument processing, and context resolution');
// Import modules
const parsingModule = await import('../../dist/execution/parsers/index.js');
// Get parsing system function from available exports
const createParsingSystem = parsingModule.createParsingSystem || parsingModule.createUnifiedParsingSystem || parsingModule.default;
// Mock logger
const mockLogger = {
debug: () => {},
info: () => {},
warn: () => {},
error: () => {}
};
// Sample prompt data for testing
const testPrompts = [
{
id: 'test_prompt',
name: 'test_prompt',
description: 'A test prompt',
userMessageTemplate: 'Test message: {{content}}',
arguments: [
{
name: 'content',
description: 'Content to process',
required: true
}
],
category: 'test'
},
{
id: 'multi_arg_prompt',
name: 'multi_arg_prompt',
description: 'A prompt with multiple arguments',
userMessageTemplate: 'Process {{text}} with {{format}}',
arguments: [
{
name: 'text',
description: 'Text to process',
required: true
},
{
name: 'format',
description: 'Output format',
required: false
}
],
category: 'test'
}
];
let parsingSystem;
// Setup for each test
function setupTest() {
parsingSystem = createParsingSystem(mockLogger);
}
// Simple assertion helpers
function assertEqual(actual, expected, testName) {
if (actual === expected) {
console.log(`✅ ${testName}: PASSED`);
return true;
} else {
console.error(`❌ ${testName}: FAILED`);
console.error(` Expected: ${expected}`);
console.error(` Actual: ${actual}`);
return false;
}
}
function assertTruthy(value, testName) {
if (value) {
console.log(`✅ ${testName}: PASSED`);
return true;
} else {
console.error(`❌ ${testName}: FAILED - Expected truthy value, got: ${value}`);
return false;
}
}
function assertLessThan(actual, expected, testName) {
if (actual < expected) {
console.log(`✅ ${testName}: PASSED (${actual} < ${expected})`);
return true;
} else {
console.error(`❌ ${testName}: FAILED (${actual} >= ${expected})`);
return false;
}
}
let testResults = [];
// Test 1: Command Parsing
console.log('🔍 Test 1: Command Parsing');
setupTest();
try {
const result1 = await parsingSystem.commandParser.parseCommand(
'>>test_prompt hello world',
testPrompts
);
testResults.push(assertEqual(result1.promptId, 'test_prompt', 'Simple command prompt ID parsed'));
testResults.push(assertEqual(result1.rawArgs, 'hello world', 'Simple command raw args parsed'));
testResults.push(assertEqual(result1.format, 'simple', 'Simple command format detected'));
} catch (error) {
console.error(`❌ Simple command parsing failed: ${error.message}`);
testResults.push(false);
}
try {
const jsonCommand = '{"command": ">>test_prompt", "args": "hello world"}';
const result2 = await parsingSystem.commandParser.parseCommand(jsonCommand, testPrompts);
testResults.push(assertEqual(result2.promptId, 'test_prompt', 'JSON command prompt ID parsed'));
testResults.push(assertEqual(result2.format, 'json', 'JSON command format detected'));
} catch (error) {
console.error(`❌ JSON command parsing failed: ${error.message}`);
testResults.push(false);
}
// Test 2: Error Handling for Unknown Prompts
console.log('🔍 Test 2: Error Handling for Unknown Prompts');
try {
await parsingSystem.commandParser.parseCommand('>>unknown_prompt', testPrompts);
console.error('❌ Unknown prompt error handling: FAILED - Should have thrown error');
testResults.push(false);
} catch (error) {
if (error.message.includes('unknown_prompt')) {
console.log('✅ Unknown prompt error handling: PASSED');
testResults.push(true);
} else {
console.error(`❌ Unknown prompt error handling: FAILED - Wrong error: ${error.message}`);
testResults.push(false);
}
}
// Test 3: Argument Processing
console.log('🔍 Test 3: Argument Processing');
try {
const simpleResult = await parsingSystem.argumentParser.parseArguments(
'hello world',
testPrompts[0]
);
testResults.push(assertEqual(simpleResult.processedArgs.content, 'hello world', 'Simple arguments processed'));
// ProcessingStrategy may not be implemented in current argument parser - that's acceptable
testResults.push(assertTruthy(typeof simpleResult.metadata === 'object', 'Simple processing metadata exists'));
} catch (error) {
console.error(`❌ Simple argument processing failed: ${error.message}`);
testResults.push(false);
}
try {
const jsonArgs = '{"text": "hello", "format": "json"}';
const jsonResult = await parsingSystem.argumentParser.parseArguments(
jsonArgs,
testPrompts[1]
);
testResults.push(assertEqual(jsonResult.processedArgs.text, 'hello', 'JSON argument text processed'));
testResults.push(assertEqual(jsonResult.processedArgs.format, 'json', 'JSON argument format processed'));
// ProcessingStrategy may not be implemented in current argument parser - that's acceptable
testResults.push(assertTruthy(typeof jsonResult.metadata === 'object', 'JSON processing metadata exists'));
} catch (error) {
console.error(`❌ JSON argument processing failed: ${error.message}`);
testResults.push(false);
}
try {
const kvArgs = 'text=hello format=xml';
const kvResult = await parsingSystem.argumentParser.parseArguments(
kvArgs,
testPrompts[1]
);
testResults.push(assertEqual(kvResult.processedArgs.text, 'hello', 'Key-value argument text processed'));
testResults.push(assertEqual(kvResult.processedArgs.format, 'xml', 'Key-value argument format processed'));
// ProcessingStrategy may not be implemented in current argument parser - that's acceptable
testResults.push(assertTruthy(typeof kvResult.metadata === 'object', 'Key-value processing metadata exists'));
} catch (error) {
console.error(`❌ Key-value argument processing failed: ${error.message}`);
testResults.push(false);
}
// Test 4: Context Resolution
console.log('🔍 Test 4: Context Resolution');
// Test environment variable resolution
process.env.PROMPT_TEST = 'environment_value';
try {
const envResult = await parsingSystem.contextResolver.resolveContext('test');
testResults.push(assertEqual(envResult.value, 'environment_value', 'Environment variable resolved'));
testResults.push(assertEqual(envResult.source, 'environment_variables', 'Environment variable source correct'));
} catch (error) {
console.error(`❌ Environment variable resolution failed: ${error.message}`);
testResults.push(false);
} finally {
delete process.env.PROMPT_TEST;
}
// Test placeholder generation
try {
const placeholderResult = await parsingSystem.contextResolver.resolveContext('unknown_key');
testResults.push(assertEqual(placeholderResult.source, 'generated_placeholder', 'Placeholder source correct'));
// Accept that placeholder may or may not include the key name - implementation detail
testResults.push(assertTruthy(typeof placeholderResult.value === 'string', 'Placeholder value is string'));
} catch (error) {
console.error(`❌ Placeholder generation failed: ${error.message}`);
testResults.push(false);
}
// Test caching
try {
await parsingSystem.contextResolver.resolveContext('cached_key');
await parsingSystem.contextResolver.resolveContext('cached_key');
const stats = parsingSystem.contextResolver.getStats();
testResults.push(assertEqual(stats.cacheHits, 1, 'Context resolution caching works'));
} catch (error) {
console.error(`❌ Context caching test failed: ${error.message}`);
testResults.push(false);
}
// Test 5: Integration Test
console.log('🔍 Test 5: End-to-End Integration');
try {
// Parse command
const parseResult = await parsingSystem.commandParser.parseCommand(
'>>multi_arg_prompt hello world',
testPrompts
);
// Process arguments with context
const context = {
conversationHistory: [],
environmentVars: {},
promptDefaults: { format: 'text' }
};
const argResult = await parsingSystem.argumentParser.parseArguments(
parseResult.rawArgs,
testPrompts[1],
context
);
testResults.push(assertEqual(parseResult.promptId, 'multi_arg_prompt', 'Integration: Command parsed'));
testResults.push(assertEqual(argResult.processedArgs.text, 'hello world', 'Integration: Arguments processed'));
} catch (error) {
console.error(`❌ Integration test failed: ${error.message}`);
testResults.push(false);
}
// Test 6: Performance Test
console.log('🔍 Test 6: Performance Validation');
const start = Date.now();
try {
for (let i = 0; i < 10; i++) {
await parsingSystem.commandParser.parseCommand(
`>>test_prompt test${i}`,
testPrompts
);
}
const duration = Date.now() - start;
testResults.push(assertLessThan(duration, 1000, 'Performance: 10 parses under 1 second'));
} catch (error) {
console.error(`❌ Performance test failed: ${error.message}`);
testResults.push(false);
}
// Test 7: Error Handling
console.log('🔍 Test 7: Error Handling');
// Test empty command handling
try {
await parsingSystem.commandParser.parseCommand('', testPrompts);
console.error('❌ Empty command handling: FAILED - Should have thrown error');
testResults.push(false);
} catch (error) {
if (error.message.includes('empty')) {
console.log('✅ Empty command handling: PASSED');
testResults.push(true);
} else {
console.error(`❌ Empty command handling: FAILED - Wrong error: ${error.message}`);
testResults.push(false);
}
}
// Results Summary
const passedTests = testResults.filter(result => result).length;
const totalTests = testResults.length;
console.log('\n📊 Unified Parsing System Unit Tests Summary:');
console.log(` ✅ Passed: ${passedTests}/${totalTests} tests`);
console.log(` 📊 Success Rate: ${((passedTests/totalTests)*100).toFixed(1)}%`);
if (passedTests === totalTests) {
console.log('🎉 All Unified Parsing System unit tests passed!');
return true;
} else {
console.error('❌ Some Unified Parsing System tests failed');
return false;
}
} catch (error) {
console.error('❌ Unified Parsing System tests failed with error:', error.message);
if (error.stack) {
console.error('Stack trace:', error.stack);
}
return false;
}
}
// Run the tests
if (import.meta.url === `file://${process.argv[1]}`) {
runUnifiedParsingTests().catch(error => {
console.error('❌ Test execution failed:', error);
process.exit(1);
});
}
export { runUnifiedParsingTests };
```
--------------------------------------------------------------------------------
/server/src/execution/types.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Execution System Type Definitions
*
* Contains all types related to prompt execution, strategies, contexts, and results.
* This includes execution strategies, converted prompts, contexts, and chain execution.
*/
import type { PromptArgument, GateDefinition } from '../prompts/types.js';
/**
* Execution strategy type enumeration - THREE-TIER MODEL
* Used by ExecutionEngine's strategy pattern for different execution modes
*
* - prompt: Basic variable substitution, no framework processing (fastest)
* - template: Framework-aware execution with methodology guidance
* - chain: Sequential execution using prompts and/or templates (includes former workflow capabilities)
*/
export type ExecutionStrategyType = 'prompt' | 'template' | 'chain';
/**
* Execution types for semantic analysis
*/
export type ExecutionType = "template" | "chain" | "auto";
/**
* Enhanced chain step definition
*/
export interface ChainStep {
// Core chain step properties
promptId: string; // ID of the prompt to execute in this step
stepName: string; // Name of this step
executionType?: 'prompt' | 'template'; // Whether to use basic prompt or framework-aware template execution
inputMapping?: Record<string, string>; // Maps chain inputs to this step's inputs
outputMapping?: Record<string, string>; // Maps this step's outputs to chain outputs
qualityGates?: GateDefinition[]; // Optional custom quality gates for this step
// Advanced chain capabilities (optional - preserves backward compatibility)
dependencies?: string[]; // Step IDs that must complete before this step (enables dependency resolution)
parallelGroup?: string; // Group ID for parallel execution (steps with same group run concurrently)
timeout?: number; // Step-specific timeout in milliseconds
retries?: number; // Number of retries for this step
stepType?: 'prompt' | 'tool' | 'gate' | 'condition'; // Extended step types beyond prompt execution
}
/**
* Comprehensive converted prompt for execution context
* Consolidates all previous ConvertedPrompt definitions
*/
export interface ConvertedPrompt {
id: string;
name: string;
description: string;
category: string;
systemMessage?: string;
userMessageTemplate: string;
arguments: PromptArgument[];
// Chain-related properties (isChain removed - now derived from chainSteps presence)
chainSteps?: ChainStep[];
tools?: boolean; // Whether this prompt should use available tools
/** Defines behavior when prompt is invoked without its defined arguments */
onEmptyInvocation?: "execute_if_possible" | "return_template";
// Gate validation properties
gates?: GateDefinition[];
// Phase 2: Template-level gate configuration
gateConfiguration?: {
include?: string[];
exclude?: string[];
framework_gates?: boolean;
};
// Phase 3: Enhanced gate configuration with temporary gates
enhancedGateConfiguration?: EnhancedGateConfiguration;
executionMode?: 'prompt' | 'template' | 'chain'; // 3-tier execution model
requiresExecution?: boolean; // Whether this prompt should be executed rather than returned
}
/**
* Base execution context for all strategies
* Provides common execution metadata across all strategy types
*/
export interface BaseExecutionContext {
/** Unique execution identifier */
id: string;
/** Strategy type being used */
type: ExecutionStrategyType;
/** Execution start timestamp */
startTime: number;
/** Input parameters for execution */
inputs: Record<string, string | number | boolean | null>;
/** Strategy-specific and user options */
options: Record<string, string | number | boolean | null | unknown[]>;
}
/**
* Chain step execution result
*/
export interface ChainStepResult {
result: string;
metadata: {
startTime: number;
endTime: number;
duration: number;
status: 'completed' | 'failed' | 'skipped';
error?: string;
};
}
/**
* Chain execution result structure
*/
export interface ChainExecutionResult {
results: Record<string, string>;
messages: {
role: "user" | "assistant";
content: { type: "text"; text: string };
}[];
}
/**
* Unified execution result interface
* Standardizes results across all execution strategies
*/
export interface UnifiedExecutionResult {
/** Unique execution identifier */
executionId: string;
/** Strategy type that was used */
type: ExecutionStrategyType;
/** Final execution status */
status: 'completed' | 'failed' | 'timeout' | 'cancelled';
/** Execution start timestamp */
startTime: number;
/** Execution end timestamp */
endTime: number;
/** Strategy-specific result content */
result: string | ChainExecutionResult;
/** Error information if execution failed */
error?: {
message: string;
code?: string;
context?: Record<string, unknown>;
};
}
/**
* Base execution strategy interface
* Defines the contract that all execution strategies must implement
*/
export interface ExecutionStrategy {
/** Strategy type identifier */
readonly type: ExecutionStrategyType;
/**
* Execute using this strategy
* @param context Base execution context
* @param promptId ID of prompt to execute
* @param args Execution arguments
*/
execute(
context: BaseExecutionContext,
promptId: string,
args: Record<string, string | number | boolean | null>
): Promise<UnifiedExecutionResult>;
/**
* Validate if this strategy can handle the given prompt
* @param prompt The prompt to validate
*/
canHandle(prompt: ConvertedPrompt): boolean;
/**
* Get strategy-specific default options
*/
getOptions(): Record<string, string | number | boolean | null | unknown[]>;
}
/**
* Execution engine statistics
* Comprehensive performance and usage metrics
*/
export interface ExecutionStats {
/** Total number of executions */
totalExecutions: number;
/** Number of prompt strategy executions */
promptExecutions: number;
/** Number of chain strategy executions */
chainExecutions: number;
/** Number of failed executions */
failedExecutions: number;
/** Average execution time in milliseconds */
averageExecutionTime: number;
/** Currently active executions */
activeExecutions: number;
/** Conversation manager statistics */
conversationStats: any;
}
/**
* Performance metrics for ExecutionEngine monitoring
* Provides detailed performance and health metrics
*/
export interface PerformanceMetrics {
/** Strategy cache hit rate (0.0 to 1.0) */
cacheHitRate: number;
/** Memory usage information */
memoryUsage: {
/** Size of strategy selection cache */
strategyCacheSize: number;
/** Number of stored execution times */
executionTimesSize: number;
/** Number of currently active executions */
activeExecutionsSize: number;
};
/** Execution health metrics */
executionHealth: {
/** Success rate (0.0 to 1.0) */
successRate: number;
/** Average execution time in milliseconds */
averageTime: number;
/** Number of recent executions tracked */
recentExecutions: number;
};
}
/**
* Enhanced Chain Execution Options
* Extends basic chain execution with optional advanced capabilities
* All advanced options are optional to preserve backward compatibility
*/
export interface EnhancedChainExecutionOptions {
// Existing basic options (maintained for backward compatibility)
allowStepFailures?: boolean; // Allow individual steps to fail without stopping chain
trackStepResults?: boolean; // Track results from each step for use in subsequent steps
useConversationContext?: boolean; // Include conversation history in step execution
processTemplates?: boolean; // Process Nunjucks templates in step prompts
// NEW: Advanced execution options (all optional - default to false/simple behavior)
enableDependencyResolution?: boolean; // Enable step dependency resolution and topological ordering
enableParallelExecution?: boolean; // Enable parallel execution of steps in same parallel group
executionTimeout?: number; // Chain-wide timeout in milliseconds (overrides individual step timeouts)
advancedGateValidation?: boolean; // Use comprehensive gate validation
stepConfirmation?: boolean; // Require confirmation before executing each step
continueOnFailure?: boolean; // Continue chain execution even if non-critical steps fail
}
/**
* Chain execution state
*/
export interface ChainExecutionState {
chainId: string;
currentStepIndex: number;
totalSteps: number;
stepResults: Record<string, string>;
startTime: number;
}
/**
* Template processing context
*/
export interface TemplateContext {
specialContext?: Record<string, string>;
toolsEnabled?: boolean;
}
/**
* Validation error detail structure
*/
export interface ValidationError {
field: string;
message: string;
code: string;
suggestion?: string;
example?: string;
}
/**
* Validation warning structure
*/
export interface ValidationWarning {
field: string;
message: string;
suggestion?: string;
}
/**
* Unified validation result structure
* Supports both simple validation and comprehensive gate validation
*/
export interface ValidationResult {
/** Whether validation passed (supports both 'valid' and 'passed' patterns) */
valid: boolean;
/** Alternative field name for gate validation compatibility */
passed?: boolean;
/** Detailed validation errors */
errors?: ValidationError[];
/** Validation warnings */
warnings?: ValidationWarning[];
/** Sanitized arguments for simple validation */
sanitizedArgs?: Record<string, string | number | boolean | null>;
// Extended fields for gate validation (optional)
/** Gate that was validated (for gate validation) */
gateId?: string;
/** Individual check results (for comprehensive validation) */
checks?: ValidationCheck[];
/** Hints for improvement on failure (for gate validation) */
retryHints?: string[];
/** Validation metadata (for comprehensive validation) */
metadata?: {
validationTime: number;
checksPerformed: number;
llmValidationUsed: boolean;
};
// Argument-specific validation (optional)
/** Argument name (for argument validation) */
argumentName?: string;
/** Original value before processing */
originalValue?: unknown;
/** Processed value after validation */
processedValue?: string | number | boolean | null;
/** Applied validation rules */
appliedRules?: string[];
}
/**
* Individual validation check result (used in comprehensive validation)
*/
export interface ValidationCheck {
/** Type of check performed */
type: string;
/** Did this check pass */
passed: boolean;
/** Score if applicable (0.0-1.0) */
score?: number;
/** Details about the check */
message: string;
/** Additional context */
details?: Record<string, any>;
}
/**
* Enhanced gate configuration supporting temporary gates
* Phase 3: Extends basic gate configuration with temporary gate support
*/
export interface EnhancedGateConfiguration {
/** Gates to explicitly include */
include?: string[];
/** Gates to explicitly exclude */
exclude?: string[];
/** Whether to include framework-based gates (default: true) */
framework_gates?: boolean;
/** Temporary gate definitions for this execution */
temporary_gates?: TemporaryGateDefinition[];
/** Scope for temporary gates */
gate_scope?: 'execution' | 'session' | 'chain' | 'step';
/** Whether to inherit gates from parent chain (default: true) */
inherit_chain_gates?: boolean;
}
/**
* Temporary gate definition for enhanced configuration
*/
export interface TemporaryGateDefinition {
/** Unique identifier (will be auto-generated if not provided) */
id?: string;
/** Human-readable name */
name: string;
/** Gate type */
type: 'validation' | 'approval' | 'condition' | 'quality' | 'guidance';
/** Scope of the temporary gate */
scope: 'execution' | 'session' | 'chain' | 'step';
/** Description of what this gate checks/guides */
description: string;
/** Guidance text injected into prompts */
guidance: string;
/** Pass/fail criteria for validation gates */
pass_criteria?: ValidationCheck[];
/** Expiration timestamp (optional) */
expires_at?: number;
/** Source of gate creation */
source?: 'manual' | 'automatic' | 'analysis';
/** Additional context for gate creation */
context?: Record<string, any>;
}
```
--------------------------------------------------------------------------------
/server/src/gates/core/temporary-gate-registry.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Temporary Gate Registry
*
* Manages in-memory storage and lifecycle for execution-scoped gates that don't persist to filesystem.
* Provides automatic cleanup, scope management, and integration with existing gate systems.
*/
import { Logger } from '../../logging/index.js';
import type { GateDefinition } from '../types.js';
/**
* Temporary gate definition with lifecycle management
*/
export interface TemporaryGateDefinition {
/** Unique identifier (UUID-based to prevent conflicts) */
id: string;
/** Human-readable name */
name: string;
/** Gate type */
type: 'validation' | 'approval' | 'condition' | 'quality' | 'guidance';
/** Scope of the temporary gate */
scope: 'execution' | 'session' | 'chain' | 'step';
/** Description of what this gate checks/guides */
description: string;
/** Guidance text injected into prompts */
guidance: string;
/** Pass/fail criteria for validation gates */
pass_criteria?: any[];
/** Creation timestamp */
created_at: number;
/** Expiration timestamp (optional) */
expires_at?: number;
/** Source of gate creation */
source: 'manual' | 'automatic' | 'analysis';
/** Additional context for gate creation */
context?: Record<string, any>;
/** Associated execution/session/chain ID */
scope_id?: string;
}
/**
* Scope management information
*/
interface ScopeInfo {
scope_type: 'execution' | 'session' | 'chain' | 'step';
scope_id: string;
gates: Set<string>;
created_at: number;
expires_at?: number;
}
/**
* Registry for managing temporary gates
*/
export class TemporaryGateRegistry {
private logger: Logger;
private temporaryGates: Map<string, TemporaryGateDefinition>;
private scopeManagement: Map<string, ScopeInfo>;
private cleanupTimers: Map<string, NodeJS.Timeout>;
private maxMemoryGates: number;
private defaultExpirationMs: number;
constructor(
logger: Logger,
options: {
maxMemoryGates?: number;
defaultExpirationMs?: number;
} = {}
) {
this.logger = logger;
this.temporaryGates = new Map();
this.scopeManagement = new Map();
this.cleanupTimers = new Map();
this.maxMemoryGates = options.maxMemoryGates || 1000;
this.defaultExpirationMs = options.defaultExpirationMs || 3600000; // 1 hour
this.logger.debug('[TEMP GATE REGISTRY] Initialized with max gates:', this.maxMemoryGates);
}
/**
* Create a new temporary gate
*/
createTemporaryGate(
definition: Omit<TemporaryGateDefinition, 'id' | 'created_at'>,
scopeId?: string
): string {
// Generate unique ID
const gateId = `temp_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
// Check memory limits
if (this.temporaryGates.size >= this.maxMemoryGates) {
this.performCleanup();
if (this.temporaryGates.size >= this.maxMemoryGates) {
throw new Error(`Temporary gate registry at capacity (${this.maxMemoryGates})`);
}
}
const now = Date.now();
const tempGate: TemporaryGateDefinition = {
id: gateId,
created_at: now,
expires_at: definition.expires_at || (now + this.defaultExpirationMs),
scope_id: scopeId,
...definition
};
// Store the gate
this.temporaryGates.set(gateId, tempGate);
// Manage scope association
if (scopeId) {
this.associateWithScope(gateId, definition.scope, scopeId);
}
// Set up automatic cleanup
if (tempGate.expires_at) {
const cleanupTimeout = setTimeout(() => {
this.removeTemporaryGate(gateId);
}, tempGate.expires_at - now);
this.cleanupTimers.set(gateId, cleanupTimeout);
}
this.logger.debug(`[TEMP GATE REGISTRY] Created temporary gate:`, {
id: gateId,
name: tempGate.name,
scope: tempGate.scope,
scopeId,
expiresAt: tempGate.expires_at
});
return gateId;
}
/**
* Get a temporary gate by ID
*/
getTemporaryGate(gateId: string): TemporaryGateDefinition | undefined {
return this.temporaryGates.get(gateId);
}
/**
* Get all temporary gates for a specific scope
*/
getTemporaryGatesForScope(scope: string, scopeId: string): TemporaryGateDefinition[] {
const scopeKey = `${scope}:${scopeId}`;
const scopeInfo = this.scopeManagement.get(scopeKey);
if (!scopeInfo) {
return [];
}
const gates: TemporaryGateDefinition[] = [];
for (const gateId of scopeInfo.gates) {
const gate = this.temporaryGates.get(gateId);
if (gate) {
gates.push(gate);
}
}
return gates;
}
/**
* Get all active temporary gates
*/
getAllTemporaryGates(): TemporaryGateDefinition[] {
return Array.from(this.temporaryGates.values());
}
/**
* Convert temporary gate to standard gate definition
*/
convertToStandardGate(tempGate: TemporaryGateDefinition): GateDefinition {
return {
id: tempGate.id,
name: tempGate.name,
type: tempGate.type,
description: tempGate.description,
requirements: [], // Temporary gates use simplified criteria
failureAction: 'retry',
guidance: tempGate.guidance,
pass_criteria: tempGate.pass_criteria,
retry_config: {
max_attempts: 3,
improvement_hints: true,
preserve_context: true
},
activation: {
explicit_request: true
}
};
}
/**
* Remove a temporary gate
*/
removeTemporaryGate(gateId: string): boolean {
const gate = this.temporaryGates.get(gateId);
if (!gate) {
return false;
}
// Remove from registry
this.temporaryGates.delete(gateId);
// Clean up scope associations
if (gate.scope_id) {
this.removeFromScope(gateId, gate.scope, gate.scope_id);
}
// Cancel cleanup timer
const timer = this.cleanupTimers.get(gateId);
if (timer) {
clearTimeout(timer);
this.cleanupTimers.delete(gateId);
}
this.logger.debug(`[TEMP GATE REGISTRY] Removed temporary gate: ${gateId}`);
return true;
}
/**
* Clean up expired gates and scopes
*/
cleanupExpiredGates(): number {
const now = Date.now();
let cleanedCount = 0;
// Clean up expired gates
for (const [gateId, gate] of this.temporaryGates.entries()) {
if (gate.expires_at && gate.expires_at <= now) {
this.removeTemporaryGate(gateId);
cleanedCount++;
}
}
// Clean up expired scopes
for (const [scopeKey, scopeInfo] of this.scopeManagement.entries()) {
if (scopeInfo.expires_at && scopeInfo.expires_at <= now) {
this.cleanupScopeByKey(scopeKey);
}
}
if (cleanedCount > 0) {
this.logger.debug(`[TEMP GATE REGISTRY] Cleaned up ${cleanedCount} expired gates`);
}
return cleanedCount;
}
/**
* Clean up all gates for a specific scope
*/
cleanupScope(scope: string, scopeId?: string): number {
const scopeKey = scopeId ? `${scope}:${scopeId}` : scope;
const scopeInfo = this.scopeManagement.get(scopeKey);
if (!scopeInfo) {
return 0;
}
let cleanedCount = 0;
for (const gateId of scopeInfo.gates) {
if (this.removeTemporaryGate(gateId)) {
cleanedCount++;
}
}
this.scopeManagement.delete(scopeKey);
this.logger.debug(`[TEMP GATE REGISTRY] Cleaned up scope ${scopeKey}: ${cleanedCount} gates`);
return cleanedCount;
}
/**
* Clean up all gates for a chain execution
* Removes all chain-scoped gates and associated step-scoped gates
*/
cleanupChainExecution(chainExecutionId: string): number {
this.logger.debug(`[TEMP GATE REGISTRY] Cleaning up chain execution: ${chainExecutionId}`);
let totalCleaned = 0;
// Clean up chain-scoped gates
totalCleaned += this.cleanupScope('chain', chainExecutionId);
// Clean up any step-scoped gates associated with this chain
const stepScopesToClean: string[] = [];
for (const [scopeKey, scopeInfo] of this.scopeManagement.entries()) {
if (scopeInfo.scope_type === 'step' && scopeKey.includes(chainExecutionId)) {
stepScopesToClean.push(scopeKey);
}
}
for (const scopeKey of stepScopesToClean) {
this.cleanupScopeByKey(scopeKey);
totalCleaned++;
}
this.logger.info(`[TEMP GATE REGISTRY] Chain ${chainExecutionId} cleanup: ${totalCleaned} gates removed`);
return totalCleaned;
}
/**
* Clean up all gates for an execution scope
* Convenience method for execution-scoped cleanups
*/
cleanupExecutionScope(executionId: string): number {
return this.cleanupScope('execution', executionId);
}
/**
* Get registry statistics
*/
getStatistics() {
const now = Date.now();
const gates = Array.from(this.temporaryGates.values());
const expiredCount = gates.filter(g => g.expires_at && g.expires_at <= now).length;
const byScope = gates.reduce((acc, gate) => {
acc[gate.scope] = (acc[gate.scope] || 0) + 1;
return acc;
}, {} as Record<string, number>);
const bySource = gates.reduce((acc, gate) => {
acc[gate.source] = (acc[gate.source] || 0) + 1;
return acc;
}, {} as Record<string, number>);
return {
totalGates: this.temporaryGates.size,
maxCapacity: this.maxMemoryGates,
utilizationPercent: Math.round((this.temporaryGates.size / this.maxMemoryGates) * 100),
expiredGates: expiredCount,
activeScopes: this.scopeManagement.size,
activeCleanupTimers: this.cleanupTimers.size,
gatesByScope: byScope,
gatesBySource: bySource,
memoryUsageEstimate: this.estimateMemoryUsage()
};
}
/**
* Force cleanup to free memory
*/
private performCleanup(): void {
this.logger.debug('[TEMP GATE REGISTRY] Performing forced cleanup');
// First try cleaning expired gates
const expiredCleaned = this.cleanupExpiredGates();
// If still at capacity, remove oldest gates
if (this.temporaryGates.size >= this.maxMemoryGates) {
const gates = Array.from(this.temporaryGates.values())
.sort((a, b) => a.created_at - b.created_at);
const toRemove = Math.min(100, gates.length - Math.floor(this.maxMemoryGates * 0.8));
for (let i = 0; i < toRemove; i++) {
this.removeTemporaryGate(gates[i].id);
}
this.logger.warn(`[TEMP GATE REGISTRY] Force removed ${toRemove} oldest gates`);
}
}
/**
* Associate gate with scope
*/
private associateWithScope(gateId: string, scope: string, scopeId: string): void {
const scopeKey = `${scope}:${scopeId}`;
if (!this.scopeManagement.has(scopeKey)) {
this.scopeManagement.set(scopeKey, {
scope_type: scope as any,
scope_id: scopeId,
gates: new Set(),
created_at: Date.now()
});
}
this.scopeManagement.get(scopeKey)!.gates.add(gateId);
}
/**
* Remove gate from scope
*/
private removeFromScope(gateId: string, scope: string, scopeId: string): void {
const scopeKey = `${scope}:${scopeId}`;
const scopeInfo = this.scopeManagement.get(scopeKey);
if (scopeInfo) {
scopeInfo.gates.delete(gateId);
// Remove scope if empty
if (scopeInfo.gates.size === 0) {
this.scopeManagement.delete(scopeKey);
}
}
}
/**
* Cleanup scope by key
*/
private cleanupScopeByKey(scopeKey: string): void {
const scopeInfo = this.scopeManagement.get(scopeKey);
if (scopeInfo) {
for (const gateId of scopeInfo.gates) {
this.removeTemporaryGate(gateId);
}
this.scopeManagement.delete(scopeKey);
}
}
/**
* Estimate memory usage
*/
private estimateMemoryUsage(): number {
// Rough estimation: 1KB per gate + scope overhead
const gateSize = this.temporaryGates.size * 1024;
const scopeSize = this.scopeManagement.size * 256;
const timerSize = this.cleanupTimers.size * 64;
return gateSize + scopeSize + timerSize;
}
/**
* Cleanup all resources
*/
destroy(): void {
this.logger.debug('[TEMP GATE REGISTRY] Destroying registry');
// Clear all timers
for (const timer of this.cleanupTimers.values()) {
clearTimeout(timer);
}
// Clear all data
this.temporaryGates.clear();
this.scopeManagement.clear();
this.cleanupTimers.clear();
}
}
/**
* Factory function for creating temporary gate registry
*/
export function createTemporaryGateRegistry(
logger: Logger,
options?: {
maxMemoryGates?: number;
defaultExpirationMs?: number;
}
): TemporaryGateRegistry {
return new TemporaryGateRegistry(logger, options);
}
```