claude-flow-novice 2.16.0 → 2.16.1

package/dist/lib/environment-contract.js

@@ -0,0 +1,258 @@
+/**
+ * Environment Variable Contract Resolver
+ *
+ * Provides single source of truth for environment variables with mode-specific overrides.
+ * Implements Phase 3 of CLI/Trigger.dev collision mitigation strategy.
+ *
+ * Reference: planning/trigger/CLI_TRIGGER_COLLISION_ANALYSIS.md (Phase 3)
+ * Contract: docker/runtime/cfn-runtime.contract.yml
+ *
+ * Variable Resolution Order (First Set Wins):
+ * 1. Mode-specific overrides (if specified in contract)
+ * 2. Environment variable with CFN_ prefix (standard)
+ * 3. Legacy environment variable (with deprecation warning)
+ * 4. Default value from contract
+ * 5. Error if no value found and required=true
+ *
+ * Usage:
+ *   import { getEnvValue } from './environment-contract';
+ *
+ *   // CLI mode - uses mcp-network
+ *   const cliRedisHost = getEnvValue('redis_host', 'cli');
+ *
+ *   // Trigger.dev mode - uses trigger-cfn-network
+ *   const triggerRedisHost = getEnvValue('redis_host', 'trigger');
+ *
+ *   // Environment override takes precedence
+ *   process.env.CFN_REDIS_HOST = 'custom-redis';
+ *   const overriddenHost = getEnvValue('redis_host', 'cli'); // Returns 'custom-redis'
+ */ import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import * as yaml from 'js-yaml';
+// ESM-compatible __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Loaded contract cache (lazy-loaded on first use)
+ */ let contractCache = null;
+/**
+ * Clears the contract cache (for testing purposes)
+ * @internal
+ */ export function _clearContractCache() {
+    contractCache = null;
+}
+/**
+ * Loads the environment variable contract from YAML file
+ * Cached after first load for performance
+ *
+ * @returns Contract specification mapping
+ * @throws Error if contract file not found or invalid YAML
+ */ function loadContract() {
+    if (contractCache) {
+        return contractCache;
+    }
+    const projectRoot = process.env.PROJECT_ROOT || path.resolve(__dirname, '../../');
+    const contractPath = path.resolve(projectRoot, 'docker/runtime/cfn-runtime.contract.yml');
+    if (!fs.existsSync(contractPath)) {
+        throw new Error(`Environment contract not found at ${contractPath}. ` + `Ensure docker/runtime/cfn-runtime.contract.yml exists.`);
+    }
+    const contractYaml = fs.readFileSync(contractPath, 'utf8');
+    const contractData = yaml.load(contractYaml);
+    // Flatten nested contract structure (e.g., redis.CFN_REDIS_HOST becomes redis_host)
+    contractCache = flattenContract(contractData);
+    return contractCache;
+}
+/**
+ * Flattens nested contract structure into flat key mapping
+ * Maps environment variable names (CFN_REDIS_HOST) to their specs
+ *
+ * @param nested - Nested contract from YAML
+ * @returns Flattened mapping with both simple keys and spec metadata
+ */ function flattenContract(nested) {
+    const flattened = {};
+    // Process each top-level category (redis, agent, task, etc.)
+    for (const [category, variables] of Object.entries(nested)){
+        // Skip metadata fields
+        if (category === 'version' || category === 'last_updated') {
+            continue;
+        }
+        if (typeof variables !== 'object' || variables === null) {
+            continue;
+        }
+        // Process each variable in category
+        for (const [envVarName, spec] of Object.entries(variables)){
+            if (typeof spec === 'object' && spec !== null) {
+                // Create a simple key from env var name (e.g., CFN_REDIS_HOST -> redis_host)
+                const simpleKey = envVarName.replace(/^CFN_/, '').toLowerCase().replace(/_/g, '_');
+                const specWithCfnName = {
+                    ...spec,
+                    _cfnVarName: envVarName
+                };
+                flattened[simpleKey] = specWithCfnName;
+            }
+        }
+    }
+    return flattened;
+}
+/**
+ * Gets environment value with mode-specific override support
+ *
+ * Resolution order:
+ * 1. Mode-specific override from contract (if defined)
+ * 2. CFN_-prefixed environment variable
+ * 3. Legacy environment variable (with warning)
+ * 4. Default from contract
+ * 5. Error if required and no value found
+ *
+ * @param key - Contract key (e.g., 'redis_host')
+ * @param mode - Execution mode ('cli' or 'trigger')
+ * @returns Resolved environment variable value as string
+ * @throws Error if key not found in contract or required value missing
+ */ export function getEnvValue(key, mode) {
+    const contract = loadContract();
+    const spec = contract[key];
+    if (!spec) {
+        throw new Error(`Unknown contract key: '${key}'. ` + `Available keys: ${Object.keys(contract).filter((k)=>!k.startsWith('_')).join(', ')}`);
+    }
+    // Get the CFN variable name for this spec
+    const cfnVarName = spec._cfnVarName || 'CFN_VAR';
+    // Step 1: Check CFN_ prefixed environment variable (highest priority explicit env var)
+    if (process.env[cfnVarName]) {
+        return process.env[cfnVarName];
+    }
+    // Step 2: Check legacy environment variables
+    if (spec.legacy_aliases && spec.legacy_aliases.length > 0) {
+        for (const legacy of spec.legacy_aliases){
+            if (process.env[legacy]) {
+                console.warn(`[ENV DEPRECATION] Using legacy environment variable '${legacy}', ` + `migrate to '${cfnVarName}' (see docker/runtime/cfn-runtime.contract.yml)`);
+                return process.env[legacy];
+            }
+        }
+    }
+    // Step 3: Use mode-specific override if no explicit env var was set
+    if (spec.modes?.[mode]?.override !== undefined) {
+        return String(spec.modes[mode].override);
+    }
+    // Step 4: Use default value
+    if (spec.default !== null && spec.default !== undefined) {
+        return String(spec.default);
+    }
+    // Step 5: Error if required
+    if (spec.required) {
+        throw new Error(`Required environment variable '${cfnVarName}' not set. ` + `See docker/runtime/cfn-runtime.contract.yml for configuration.`);
+    }
+    // No value found and not required - return empty string
+    return '';
+}
+/**
+ * Gets mode-specific network name from contract
+ *
+ * @param mode - Execution mode ('cli' or 'trigger')
+ * @returns Network name for the mode
+ */ export function getNetworkName(mode) {
+    const contract = loadContract();
+    const spec = contract['network_name'];
+    if (!spec) {
+        // Fallback to default if not in contract
+        return mode === 'cli' ? 'mcp-network' : 'trigger-cfn-network';
+    }
+    return getEnvValue('network_name', mode);
+}
+/**
+ * Gets all environment variables for a specific mode
+ * Useful for Docker environment setup
+ *
+ * @param mode - Execution mode ('cli' or 'trigger')
+ * @returns Object with resolved environment variables
+ */ export function getAllEnvValues(mode) {
+    const contract = loadContract();
+    const envVars = {};
+    for (const [key, spec] of Object.entries(contract)){
+        if (spec && typeof spec === 'object' && 'description' in spec) {
+            try {
+                const value = getEnvValue(key, mode);
+                if (value) {
+                    envVars[key] = value;
+                }
+            } catch  {
+            // Skip variables that can't be resolved (optional)
+            }
+        }
+    }
+    return envVars;
+}
+/**
+ * Validates an environment variable against contract rules
+ *
+ * @param key - Contract key
+ * @param value - Value to validate
+ * @returns Validation result with optional error message
+ */ export function validateEnvValue(key, value) {
+    const contract = loadContract();
+    const spec = contract[key];
+    if (!spec) {
+        return {
+            valid: false,
+            error: `Unknown contract key: '${key}'`
+        };
+    }
+    const rules = spec.validation;
+    if (!rules) {
+        return {
+            valid: true
+        };
+    }
+    // Pattern validation
+    if (rules.pattern) {
+        const regex = new RegExp(rules.pattern);
+        if (!regex.test(value)) {
+            return {
+                valid: false,
+                error: `Value '${value}' does not match pattern '${rules.pattern}'`
+            };
+        }
+    }
+    // Numeric validations
+    if (spec.type === 'integer' || spec.type === 'float') {
+        const numValue = spec.type === 'integer' ? parseInt(value, 10) : parseFloat(value);
+        if (isNaN(numValue)) {
+            return {
+                valid: false,
+                error: `Value '${value}' is not a valid ${spec.type}`
+            };
+        }
+        if (rules.min !== undefined && numValue < rules.min) {
+            return {
+                valid: false,
+                error: `Value ${numValue} is less than minimum ${rules.min}`
+            };
+        }
+        if (rules.max !== undefined && numValue > rules.max) {
+            return {
+                valid: false,
+                error: `Value ${numValue} is greater than maximum ${rules.max}`
+            };
+        }
+    }
+    // Allowed values
+    if (rules.allowed_values && !rules.allowed_values.includes(value)) {
+        return {
+            valid: false,
+            error: `Value '${value}' is not in allowed values: ${rules.allowed_values.join(', ')}`
+        };
+    }
+    return {
+        valid: true
+    };
+}
+/**
+ * Exports for barrel import
+ */ export default {
+    getEnvValue,
+    getNetworkName,
+    getAllEnvValues,
+    validateEnvValue
+};
+
+//# sourceMappingURL=environment-contract.js.map

package/dist/lib/environment-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/environment-contract.ts"],"sourcesContent":["/**\r\n * Environment Variable Contract Resolver\r\n *\r\n * Provides single source of truth for environment variables with mode-specific overrides.\r\n * Implements Phase 3 of CLI/Trigger.dev collision mitigation strategy.\r\n *\r\n * Reference: planning/trigger/CLI_TRIGGER_COLLISION_ANALYSIS.md (Phase 3)\r\n * Contract: docker/runtime/cfn-runtime.contract.yml\r\n *\r\n * Variable Resolution Order (First Set Wins):\r\n * 1. Mode-specific overrides (if specified in contract)\r\n * 2. Environment variable with CFN_ prefix (standard)\r\n * 3. Legacy environment variable (with deprecation warning)\r\n * 4. Default value from contract\r\n * 5. Error if no value found and required=true\r\n *\r\n * Usage:\r\n *   import { getEnvValue } from './environment-contract';\r\n *\r\n *   // CLI mode - uses mcp-network\r\n *   const cliRedisHost = getEnvValue('redis_host', 'cli');\r\n *\r\n *   // Trigger.dev mode - uses trigger-cfn-network\r\n *   const triggerRedisHost = getEnvValue('redis_host', 'trigger');\r\n *\r\n *   // Environment override takes precedence\r\n *   process.env.CFN_REDIS_HOST = 'custom-redis';\r\n *   const overriddenHost = getEnvValue('redis_host', 'cli'); // Returns 'custom-redis'\r\n */\r\n\r\nimport * as fs from 'fs';\r\nimport * as path from 'path';\r\nimport { fileURLToPath } from 'url';\r\nimport * as yaml from 'js-yaml';\r\n\r\n// ESM-compatible __dirname\r\nconst __filename = fileURLToPath(import.meta.url);\r\nconst __dirname = path.dirname(__filename);\r\n\r\n/**\r\n * Validation constraints for contract values\r\n */\r\ninterface ValidationRules {\r\n  pattern?: string;\r\n  min?: number;\r\n  max?: number;\r\n  allowed_values?: string[];\r\n  description?: string;\r\n}\r\n\r\n/**\r\n * Mode-specific overrides in contract\r\n */\r\ninterface ModeOverride {\r\n  override?: string | number;\r\n  network?: string;\r\n}\r\n\r\n/**\r\n * Contract specification for a single environment variable\r\n */\r\ninterface ContractSpec {\r\n  description: string;\r\n  default: string | number | null;\r\n  type: 'string' | 'integer' | 'boolean' | 'float';\r\n  scope: string[];\r\n  legacy_aliases?: string[];\r\n  required?: boolean;\r\n  required_in_production?: boolean;\r\n  example?: string;\r\n  security_notes?: string;\r\n  validation?: ValidationRules;\r\n  mode_defaults?: Record<string, string | number>;\r\n  modes?: {\r\n    cli?: ModeOverride;\r\n    trigger?: ModeOverride;\r\n  };\r\n}\r\n\r\n/**\r\n * Loaded contract cache (lazy-loaded on first use)\r\n */\r\nlet contractCache: Record<string, ContractSpec & { _cfnVarName?: string }> | null = null;\r\n\r\n/**\r\n * Clears the contract cache (for testing purposes)\r\n * @internal\r\n */\r\nexport function _clearContractCache(): void {\r\n  contractCache = null;\r\n}\r\n\r\n/**\r\n * Loads the environment variable contract from YAML file\r\n * Cached after first load for performance\r\n *\r\n * @returns Contract specification mapping\r\n * @throws Error if contract file not found or invalid YAML\r\n */\r\nfunction loadContract(): Record<string, ContractSpec> {\r\n  if (contractCache) {\r\n    return contractCache;\r\n  }\r\n\r\n  const projectRoot = process.env.PROJECT_ROOT || path.resolve(__dirname, '../../');\r\n  const contractPath = path.resolve(projectRoot, 'docker/runtime/cfn-runtime.contract.yml');\r\n\r\n  if (!fs.existsSync(contractPath)) {\r\n    throw new Error(\r\n      `Environment contract not found at ${contractPath}. ` +\r\n        `Ensure docker/runtime/cfn-runtime.contract.yml exists.`\r\n    );\r\n  }\r\n\r\n  const contractYaml = fs.readFileSync(contractPath, 'utf8');\r\n  const contractData = yaml.load(contractYaml) as Record<string, any>;\r\n\r\n  // Flatten nested contract structure (e.g., redis.CFN_REDIS_HOST becomes redis_host)\r\n  contractCache = flattenContract(contractData);\r\n\r\n  return contractCache;\r\n}\r\n\r\n/**\r\n * Flattens nested contract structure into flat key mapping\r\n * Maps environment variable names (CFN_REDIS_HOST) to their specs\r\n *\r\n * @param nested - Nested contract from YAML\r\n * @returns Flattened mapping with both simple keys and spec metadata\r\n */\r\nfunction flattenContract(nested: Record<string, any>): Record<string, ContractSpec & { _cfnVarName?: string }> {\r\n  const flattened: Record<string, ContractSpec & { _cfnVarName?: string }> = {};\r\n\r\n  // Process each top-level category (redis, agent, task, etc.)\r\n  for (const [category, variables] of Object.entries(nested)) {\r\n    // Skip metadata fields\r\n    if (category === 'version' || category === 'last_updated') {\r\n      continue;\r\n    }\r\n\r\n    if (typeof variables !== 'object' || variables === null) {\r\n      continue;\r\n    }\r\n\r\n    // Process each variable in category\r\n    for (const [envVarName, spec] of Object.entries(variables)) {\r\n      if (typeof spec === 'object' && spec !== null) {\r\n        // Create a simple key from env var name (e.g., CFN_REDIS_HOST -> redis_host)\r\n        const simpleKey = envVarName\r\n          .replace(/^CFN_/, '')\r\n          .toLowerCase()\r\n          .replace(/_/g, '_');\r\n\r\n        const specWithCfnName = {\r\n          ...(spec as ContractSpec),\r\n          _cfnVarName: envVarName, // Store the CFN variable name for later lookup\r\n        };\r\n\r\n        flattened[simpleKey] = specWithCfnName;\r\n      }\r\n    }\r\n  }\r\n\r\n  return flattened;\r\n}\r\n\r\n/**\r\n * Gets environment value with mode-specific override support\r\n *\r\n * Resolution order:\r\n * 1. Mode-specific override from contract (if defined)\r\n * 2. CFN_-prefixed environment variable\r\n * 3. Legacy environment variable (with warning)\r\n * 4. Default from contract\r\n * 5. Error if required and no value found\r\n *\r\n * @param key - Contract key (e.g., 'redis_host')\r\n * @param mode - Execution mode ('cli' or 'trigger')\r\n * @returns Resolved environment variable value as string\r\n * @throws Error if key not found in contract or required value missing\r\n */\r\nexport function getEnvValue(key: string, mode: 'cli' | 'trigger'): string {\r\n  const contract = loadContract();\r\n  const spec = contract[key] as (ContractSpec & { _cfnVarName?: string }) | undefined;\r\n\r\n  if (!spec) {\r\n    throw new Error(\r\n      `Unknown contract key: '${key}'. ` +\r\n        `Available keys: ${Object.keys(contract).filter(k => !k.startsWith('_')).join(', ')}`\r\n    );\r\n  }\r\n\r\n  // Get the CFN variable name for this spec\r\n  const cfnVarName = spec._cfnVarName || 'CFN_VAR';\r\n\r\n  // Step 1: Check CFN_ prefixed environment variable (highest priority explicit env var)\r\n  if (process.env[cfnVarName]) {\r\n    return process.env[cfnVarName];\r\n  }\r\n\r\n  // Step 2: Check legacy environment variables\r\n  if (spec.legacy_aliases && spec.legacy_aliases.length > 0) {\r\n    for (const legacy of spec.legacy_aliases) {\r\n      if (process.env[legacy]) {\r\n        console.warn(\r\n          `[ENV DEPRECATION] Using legacy environment variable '${legacy}', ` +\r\n            `migrate to '${cfnVarName}' (see docker/runtime/cfn-runtime.contract.yml)`\r\n        );\r\n        return process.env[legacy];\r\n      }\r\n    }\r\n  }\r\n\r\n  // Step 3: Use mode-specific override if no explicit env var was set\r\n  if (spec.modes?.[mode]?.override !== undefined) {\r\n    return String(spec.modes[mode].override);\r\n  }\r\n\r\n  // Step 4: Use default value\r\n  if (spec.default !== null && spec.default !== undefined) {\r\n    return String(spec.default);\r\n  }\r\n\r\n  // Step 5: Error if required\r\n  if (spec.required) {\r\n    throw new Error(\r\n      `Required environment variable '${cfnVarName}' not set. ` +\r\n        `See docker/runtime/cfn-runtime.contract.yml for configuration.`\r\n    );\r\n  }\r\n\r\n  // No value found and not required - return empty string\r\n  return '';\r\n}\r\n\r\n/**\r\n * Gets mode-specific network name from contract\r\n *\r\n * @param mode - Execution mode ('cli' or 'trigger')\r\n * @returns Network name for the mode\r\n */\r\nexport function getNetworkName(mode: 'cli' | 'trigger'): string {\r\n  const contract = loadContract();\r\n  const spec = contract['network_name'];\r\n\r\n  if (!spec) {\r\n    // Fallback to default if not in contract\r\n    return mode === 'cli' ? 'mcp-network' : 'trigger-cfn-network';\r\n  }\r\n\r\n  return getEnvValue('network_name', mode);\r\n}\r\n\r\n/**\r\n * Gets all environment variables for a specific mode\r\n * Useful for Docker environment setup\r\n *\r\n * @param mode - Execution mode ('cli' or 'trigger')\r\n * @returns Object with resolved environment variables\r\n */\r\nexport function getAllEnvValues(mode: 'cli' | 'trigger'): Record<string, string> {\r\n  const contract = loadContract();\r\n  const envVars: Record<string, string> = {};\r\n\r\n  for (const [key, spec] of Object.entries(contract)) {\r\n    if (spec && typeof spec === 'object' && 'description' in spec) {\r\n      try {\r\n        const value = getEnvValue(key, mode);\r\n        if (value) {\r\n          envVars[key] = value;\r\n        }\r\n      } catch {\r\n        // Skip variables that can't be resolved (optional)\r\n      }\r\n    }\r\n  }\r\n\r\n  return envVars;\r\n}\r\n\r\n/**\r\n * Validates an environment variable against contract rules\r\n *\r\n * @param key - Contract key\r\n * @param value - Value to validate\r\n * @returns Validation result with optional error message\r\n */\r\nexport function validateEnvValue(key: string, value: string): { valid: boolean; error?: string } {\r\n  const contract = loadContract();\r\n  const spec = contract[key];\r\n\r\n  if (!spec) {\r\n    return { valid: false, error: `Unknown contract key: '${key}'` };\r\n  }\r\n\r\n  const rules = spec.validation;\r\n  if (!rules) {\r\n    return { valid: true };\r\n  }\r\n\r\n  // Pattern validation\r\n  if (rules.pattern) {\r\n    const regex = new RegExp(rules.pattern);\r\n    if (!regex.test(value)) {\r\n      return {\r\n        valid: false,\r\n        error: `Value '${value}' does not match pattern '${rules.pattern}'`,\r\n      };\r\n    }\r\n  }\r\n\r\n  // Numeric validations\r\n  if (spec.type === 'integer' || spec.type === 'float') {\r\n    const numValue = spec.type === 'integer' ? parseInt(value, 10) : parseFloat(value);\r\n\r\n    if (isNaN(numValue)) {\r\n      return {\r\n        valid: false,\r\n        error: `Value '${value}' is not a valid ${spec.type}`,\r\n      };\r\n    }\r\n\r\n    if (rules.min !== undefined && numValue < rules.min) {\r\n      return {\r\n        valid: false,\r\n        error: `Value ${numValue} is less than minimum ${rules.min}`,\r\n      };\r\n    }\r\n\r\n    if (rules.max !== undefined && numValue > rules.max) {\r\n      return {\r\n        valid: false,\r\n        error: `Value ${numValue} is greater than maximum ${rules.max}`,\r\n      };\r\n    }\r\n  }\r\n\r\n  // Allowed values\r\n  if (rules.allowed_values && !rules.allowed_values.includes(value)) {\r\n    return {\r\n      valid: false,\r\n      error: `Value '${value}' is not in allowed values: ${rules.allowed_values.join(', ')}`,\r\n    };\r\n  }\r\n\r\n  return { valid: true };\r\n}\r\n\r\n\r\n/**\r\n * Exports for barrel import\r\n */\r\nexport default {\r\n  getEnvValue,\r\n  getNetworkName,\r\n  getAllEnvValues,\r\n  validateEnvValue,\r\n};\r\n"],"names":["fs","path","fileURLToPath","yaml","__filename","url","__dirname","dirname","contractCache","_clearContractCache","loadContract","projectRoot","process","env","PROJECT_ROOT","resolve","contractPath","existsSync","Error","contractYaml","readFileSync","contractData","load","flattenContract","nested","flattened","category","variables","Object","entries","envVarName","spec","simpleKey","replace","toLowerCase","specWithCfnName","_cfnVarName","getEnvValue","key","mode","contract","keys","filter","k","startsWith","join","cfnVarName","legacy_aliases","length","legacy","console","warn","modes","override","undefined","String","default","required","getNetworkName","getAllEnvValues","envVars","value","validateEnvValue","valid","error","rules","validation","pattern","regex","RegExp","test","type","numValue","parseInt","parseFloat","isNaN","min","max","allowed_values","includes"],"mappings":"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"}

package/dist/lib/query-optimizer.js

@@ -0,0 +1,388 @@
+/**
+ * Query Optimizer
+ *
+ * Implements database query optimizations including:
+ * - Index management for agents table
+ * - Materialized views for cost aggregation
+ * - Query pattern optimization
+ * - Expected: 10-20x query speedup
+ *
+ * Features:
+ * - Automated index creation
+ * - Materialized view management
+ * - Query rewriting for optimal execution
+ * - Performance monitoring
+ */ export class QueryOptimizer {
+    pool;
+    refreshInterval;
+    refreshTimer = null;
+    constructor(config){
+        this.pool = config.pool;
+        this.refreshInterval = config.refreshInterval || 3600000; // 1 hour default
+    }
+    /**
+   * Initialize all query optimizations
+   */ async initialize() {
+        console.log('Initializing query optimizer...');
+        await this.createIndexes();
+        await this.createMaterializedViews();
+        await this.startMaterializedViewRefresh();
+        console.log('Query optimizer initialized successfully');
+    }
+    /**
+   * Create indexes on agents table for performance
+   * Indexes: team_id, status, spawned_at
+   */ async createIndexes() {
+        const indexes = [
+            {
+                name: 'idx_agents_team_id',
+                table: 'agents',
+                columns: [
+                    'team_id'
+                ],
+                description: 'Index for team-based queries'
+            },
+            {
+                name: 'idx_agents_status',
+                table: 'agents',
+                columns: [
+                    'status'
+                ],
+                description: 'Index for status filtering'
+            },
+            {
+                name: 'idx_agents_spawned_at',
+                table: 'agents',
+                columns: [
+                    'spawned_at'
+                ],
+                description: 'Index for time-based queries'
+            },
+            {
+                name: 'idx_agents_team_status',
+                table: 'agents',
+                columns: [
+                    'team_id',
+                    'status'
+                ],
+                description: 'Composite index for team + status queries'
+            },
+            {
+                name: 'idx_agents_status_spawned',
+                table: 'agents',
+                columns: [
+                    'status',
+                    'spawned_at'
+                ],
+                description: 'Composite index for status + time queries'
+            },
+            {
+                name: 'idx_agents_cost_query',
+                table: 'agents',
+                columns: [
+                    'team_id',
+                    'spawned_at',
+                    'status'
+                ],
+                description: 'Composite index for cost aggregation queries'
+            }
+        ];
+        const client = await this.pool.connect();
+        try {
+            for (const index of indexes){
+                const query = `
+          CREATE INDEX IF NOT EXISTS ${index.name}
+          ON ${index.table} (${index.columns.join(', ')})
+        `;
+                await client.query(query);
+                console.log(`Created index: ${index.name} - ${index.description}`);
+            }
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Create materialized views for cost aggregation queries
+   */ async createMaterializedViews() {
+        const client = await this.pool.connect();
+        try {
+            // Drop existing views if they exist
+            await client.query('DROP MATERIALIZED VIEW IF EXISTS mv_cost_by_team CASCADE');
+            await client.query('DROP MATERIALIZED VIEW IF EXISTS mv_cost_by_agent_type CASCADE');
+            await client.query('DROP MATERIALIZED VIEW IF EXISTS mv_daily_cost_summary CASCADE');
+            // Create materialized view for cost by team
+            await client.query(`
+        CREATE MATERIALIZED VIEW mv_cost_by_team AS
+        SELECT
+          team_id,
+          COUNT(*) as agent_count,
+          SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed_count,
+          SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failed_count,
+          AVG(confidence) as avg_confidence,
+          SUM(COALESCE(metadata::json->>'cost', '0')::numeric) as total_cost,
+          MIN(spawned_at) as first_spawn,
+          MAX(spawned_at) as last_spawn
+        FROM agents
+        WHERE team_id IS NOT NULL
+        GROUP BY team_id
+      `);
+            console.log('Created materialized view: mv_cost_by_team');
+            // Create materialized view for cost by agent type
+            await client.query(`
+        CREATE MATERIALIZED VIEW mv_cost_by_agent_type AS
+        SELECT
+          type as agent_type,
+          COUNT(*) as agent_count,
+          SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed_count,
+          SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failed_count,
+          AVG(confidence) as avg_confidence,
+          SUM(COALESCE(metadata::json->>'cost', '0')::numeric) as total_cost,
+          AVG(EXTRACT(EPOCH FROM (completed_at - spawned_at))) as avg_duration_seconds
+        FROM agents
+        WHERE type IS NOT NULL
+        GROUP BY type
+      `);
+            console.log('Created materialized view: mv_cost_by_agent_type');
+            // Create materialized view for daily cost summary
+            await client.query(`
+        CREATE MATERIALIZED VIEW mv_daily_cost_summary AS
+        SELECT
+          DATE(spawned_at) as date,
+          COUNT(*) as total_agents,
+          SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed_count,
+          SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failed_count,
+          SUM(COALESCE(metadata::json->>'cost', '0')::numeric) as total_cost,
+          AVG(confidence) as avg_confidence
+        FROM agents
+        WHERE spawned_at IS NOT NULL
+        GROUP BY DATE(spawned_at)
+        ORDER BY date DESC
+      `);
+            console.log('Created materialized view: mv_daily_cost_summary');
+            // Create UNIQUE indexes on materialized views (required for CONCURRENT refresh)
+            await client.query('CREATE UNIQUE INDEX idx_mv_cost_by_team_team_id ON mv_cost_by_team (team_id)');
+            await client.query('CREATE UNIQUE INDEX idx_mv_cost_by_agent_type_type ON mv_cost_by_agent_type (agent_type)');
+            await client.query('CREATE UNIQUE INDEX idx_mv_daily_cost_summary_date ON mv_daily_cost_summary (date)');
+            console.log('Created UNIQUE indexes on materialized views for concurrent refresh');
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Refresh materialized views
+   */ async refreshMaterializedViews() {
+        const client = await this.pool.connect();
+        try {
+            console.log('Refreshing materialized views...');
+            await client.query('REFRESH MATERIALIZED VIEW CONCURRENTLY mv_cost_by_team');
+            await client.query('REFRESH MATERIALIZED VIEW CONCURRENTLY mv_cost_by_agent_type');
+            await client.query('REFRESH MATERIALIZED VIEW CONCURRENTLY mv_daily_cost_summary');
+            console.log('Materialized views refreshed successfully');
+        } catch (err) {
+            console.error('Error refreshing materialized views:', err);
+            throw err;
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Start automatic materialized view refresh
+   */ startMaterializedViewRefresh() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+        }
+        // Initial refresh
+        this.refreshMaterializedViews().catch(console.error);
+        // Schedule periodic refresh
+        this.refreshTimer = setInterval(()=>{
+            this.refreshMaterializedViews().catch(console.error);
+        }, this.refreshInterval);
+        console.log(`Started materialized view auto-refresh (interval: ${this.refreshInterval / 1000}s)`);
+    }
+    /**
+   * Stop automatic materialized view refresh
+   */ stopMaterializedViewRefresh() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+            console.log('Stopped materialized view auto-refresh');
+        }
+    }
+    /**
+   * Optimized query: Get cost by team
+   */ async getCostByTeam(teamId) {
+        const client = await this.pool.connect();
+        try {
+            let query = 'SELECT * FROM mv_cost_by_team';
+            const params = [];
+            if (teamId) {
+                query += ' WHERE team_id = $1';
+                params.push(teamId);
+            }
+            query += ' ORDER BY total_cost DESC';
+            const result = await client.query(query, params);
+            return result.rows;
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Optimized query: Get cost by agent type
+   */ async getCostByAgentType(agentType) {
+        const client = await this.pool.connect();
+        try {
+            let query = 'SELECT * FROM mv_cost_by_agent_type';
+            const params = [];
+            if (agentType) {
+                query += ' WHERE agent_type = $1';
+                params.push(agentType);
+            }
+            query += ' ORDER BY total_cost DESC';
+            const result = await client.query(query, params);
+            return result.rows;
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Optimized query: Get daily cost summary
+   */ async getDailyCostSummary(startDate, endDate) {
+        const client = await this.pool.connect();
+        try {
+            let query = 'SELECT * FROM mv_daily_cost_summary';
+            const params = [];
+            const conditions = [];
+            if (startDate) {
+                params.push(startDate);
+                conditions.push(`date >= $${params.length}`);
+            }
+            if (endDate) {
+                params.push(endDate);
+                conditions.push(`date <= $${params.length}`);
+            }
+            if (conditions.length > 0) {
+                query += ' WHERE ' + conditions.join(' AND ');
+            }
+            query += ' ORDER BY date DESC';
+            const result = await client.query(query, params);
+            return result.rows;
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Optimized query: Get agents by team and status
+   * Uses composite index idx_agents_team_status
+   */ async getAgentsByTeamAndStatus(teamId, status) {
+        const client = await this.pool.connect();
+        try {
+            const query = `
+        SELECT *
+        FROM agents
+        WHERE team_id = $1 AND status = $2
+        ORDER BY spawned_at DESC
+      `;
+            const result = await client.query(query, [
+                teamId,
+                status
+            ]);
+            return result.rows;
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Optimized query: Get agents by status and time range
+   * Uses composite index idx_agents_status_spawned
+   */ async getAgentsByStatusAndTimeRange(status, startDate, endDate) {
+        const client = await this.pool.connect();
+        try {
+            const query = `
+        SELECT *
+        FROM agents
+        WHERE status = $1
+          AND spawned_at >= $2
+          AND spawned_at <= $3
+        ORDER BY spawned_at DESC
+      `;
+            const result = await client.query(query, [
+                status,
+                startDate,
+                endDate
+            ]);
+            return result.rows;
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Analyze query performance
+   */ async analyzeQuery(query, params) {
+        const client = await this.pool.connect();
+        try {
+            const explainQuery = `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ${query}`;
+            const result = await client.query(explainQuery, params);
+            return result.rows[0]['QUERY PLAN'][0];
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Get index usage statistics
+   */ async getIndexUsageStats() {
+        const client = await this.pool.connect();
+        try {
+            const query = `
+        SELECT
+          schemaname,
+          tablename,
+          indexname,
+          idx_scan as index_scans,
+          idx_tup_read as tuples_read,
+          idx_tup_fetch as tuples_fetched
+        FROM pg_stat_user_indexes
+        WHERE schemaname = 'public'
+        ORDER BY idx_scan DESC
+      `;
+            const result = await client.query(query);
+            return result.rows;
+        } finally{
+            client.release();
+        }
+    }
+    /**
+   * Shutdown query optimizer
+   */ async shutdown() {
+        this.stopMaterializedViewRefresh();
+        console.log('Query optimizer shutdown complete');
+    }
+}
+// Singleton instance
+let queryOptimizerInstance = null;
+/**
+ * Initialize singleton query optimizer
+ */ export async function initQueryOptimizer(config) {
+    if (!queryOptimizerInstance) {
+        queryOptimizerInstance = new QueryOptimizer(config);
+        await queryOptimizerInstance.initialize();
+    }
+    return queryOptimizerInstance;
+}
+/**
+ * Get singleton query optimizer instance
+ */ export function getQueryOptimizer() {
+    if (!queryOptimizerInstance) {
+        throw new Error('Query optimizer not initialized. Call initQueryOptimizer first.');
+    }
+    return queryOptimizerInstance;
+}
+/**
+ * Shutdown singleton query optimizer
+ */ export async function shutdownQueryOptimizer() {
+    if (queryOptimizerInstance) {
+        await queryOptimizerInstance.shutdown();
+        queryOptimizerInstance = null;
+    }
+}
+
+//# sourceMappingURL=query-optimizer.js.map