@polymorphism-tech/morph-spec 4.2.0 → 4.3.1

package/src/lib/hooks/stop-hook-executor.js

@@ -0,0 +1,286 @@
+/**
+ * Stop Hook Executor — L-Thread validation loops
+ *
+ * Manages stop hooks for Long-Running threads.
+ * Executes hook scripts, captures output, provides structured feedback.
+ *
+ * On failure: writes feedback to .morph/stop-hook-feedback/{threadId}.json
+ * Agent reads feedback before retrying.
+ *
+ * Max retries: 5. Interval: configurable (default: 30 min).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import { recordEvent } from '../analytics/analytics-engine.js';
+
+const FEEDBACK_DIR = join(process.cwd(), '.morph/stop-hook-feedback');
+const MAX_RETRIES = 5;
+const DEFAULT_INTERVAL_MINUTES = 30;
+
+// Hook registry — hooks registered for each thread
+const hookRegistry = new Map(); // threadId → [{ hookPath, config }]
+
+// ============================================================================
+// Hook Registration
+// ============================================================================
+
+/**
+ * Register a stop hook for a thread
+ * @param {string} threadId - Thread ID
+ * @param {string} hookPath - Path to hook script
+ * @param {Object} [config]
+ * @param {string[]} [config.triggers] - When to run: ['interval', 'on-stop', 'on-error']
+ * @param {number} [config.intervalMinutes] - Interval for periodic execution
+ * @param {boolean} [config.blocking] - Whether failure blocks thread progress
+ */
+export function registerStopHook(threadId, hookPath, config = {}) {
+  if (!hookRegistry.has(threadId)) {
+    hookRegistry.set(threadId, []);
+  }
+
+  hookRegistry.get(threadId).push({
+    hookPath,
+    config: {
+      triggers: config.triggers || ['on-stop'],
+      intervalMinutes: config.intervalMinutes || DEFAULT_INTERVAL_MINUTES,
+      blocking: config.blocking !== false,
+      ...config
+    }
+  });
+}
+
+/**
+ * Get registered hooks for a thread
+ * @param {string} threadId
+ * @returns {Array}
+ */
+export function getThreadHooks(threadId) {
+  return hookRegistry.get(threadId) || [];
+}
+
+// ============================================================================
+// Hook Execution
+// ============================================================================
+
+/**
+ * Execute all stop hooks for a thread
+ * @param {string} threadId - Thread ID
+ * @param {string} hookType - Trigger type ('interval' | 'on-stop' | 'on-error')
+ * @param {Object} [context] - Additional context passed to hooks
+ * @returns {Promise<Object>} { passed, feedback, results }
+ */
+export async function executeStopHooks(threadId, hookType = 'on-stop', context = {}) {
+  const hooks = hookRegistry.get(threadId) || loadDefaultHooks(threadId);
+  const results = [];
+  let allPassed = true;
+
+  for (const hook of hooks) {
+    if (!hook.config.triggers.includes(hookType) && !hook.config.triggers.includes('all')) {
+      continue;
+    }
+
+    const result = await executeHook(hook.hookPath, { threadId, hookType, ...context });
+    results.push(result);
+
+    if (!result.passed && hook.config.blocking) {
+      allPassed = false;
+    }
+  }
+
+  const passed = allPassed;
+  const feedback = buildFeedback(results, passed);
+
+  if (!passed) {
+    saveFeedback(threadId, feedback);
+  }
+
+  recordEvent({
+    type: passed ? 'stop_hook_passed' : 'stop_hook_failed',
+    data: { threadId, hookType, resultsCount: results.length, passed }
+  });
+
+  return { passed, feedback, results };
+}
+
+/**
+ * Execute a single hook script
+ * @param {string} hookPath - Path to hook script
+ * @param {Object} context - Context passed as environment variables
+ * @returns {Promise<Object>} { hookPath, passed, output, error }
+ */
+async function executeHook(hookPath, context) {
+  const fullPath = existsSync(hookPath) ? hookPath : join(process.cwd(), hookPath);
+
+  if (!existsSync(fullPath)) {
+    return {
+      hookPath,
+      passed: true, // Missing hooks don't block
+      output: null,
+      error: `Hook not found: ${hookPath} (skipped)`,
+      skipped: true
+    };
+  }
+
+  try {
+    const env = {
+      ...process.env,
+      MORPH_THREAD_ID: context.threadId || '',
+      MORPH_HOOK_TYPE: context.hookType || '',
+      MORPH_FEATURE: context.feature || ''
+    };
+
+    const output = execSync(`node "${fullPath}"`, {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 120000, // 2 minute timeout per hook
+      env
+    });
+
+    // Parse JSON output from hook
+    let parsed;
+    try {
+      parsed = JSON.parse(output);
+    } catch {
+      // Non-JSON output means pass (for legacy hooks)
+      parsed = { passed: true, output };
+    }
+
+    return {
+      hookPath,
+      passed: parsed.passed !== false,
+      output: parsed,
+      error: parsed.error || null
+    };
+  } catch (err) {
+    return {
+      hookPath,
+      passed: false,
+      output: null,
+      error: err.message || 'Hook execution failed'
+    };
+  }
+}
+
+// ============================================================================
+// Feedback Management
+// ============================================================================
+
+/**
+ * Build structured feedback from hook results
+ * @param {Array} results - Hook execution results
+ * @param {boolean} passed - Overall pass/fail
+ * @returns {Object} Structured feedback
+ */
+function buildFeedback(results, passed) {
+  const failures = results.filter(r => !r.passed && !r.skipped);
+  const issues = failures.flatMap(r => {
+    const output = r.output;
+    if (output?.issues) return output.issues;
+    if (output?.errors) return output.errors;
+    if (r.error) return [{ message: r.error, severity: 'error' }];
+    return [];
+  });
+
+  return {
+    passed,
+    timestamp: new Date().toISOString(),
+    hooksRun: results.length,
+    hooksFailed: failures.length,
+    issues,
+    suggestions: failures.flatMap(r => r.output?.suggestions || []),
+    nextAction: passed
+      ? 'continue'
+      : failures.length > 0 ? 'fix-and-retry' : 'investigate'
+  };
+}
+
+/**
+ * Save feedback to file for agent to read
+ * @param {string} threadId - Thread ID
+ * @param {Object} feedback - Feedback object
+ * @returns {string} Path to feedback file
+ */
+export function saveFeedback(threadId, feedback) {
+  if (!existsSync(FEEDBACK_DIR)) {
+    mkdirSync(FEEDBACK_DIR, { recursive: true });
+  }
+
+  const filePath = join(FEEDBACK_DIR, `${threadId}.json`);
+  writeFileSync(filePath, JSON.stringify(feedback, null, 2), 'utf8');
+  return filePath;
+}
+
+/**
+ * Load feedback for a thread (agent reads this after failure)
+ * @param {string} threadId - Thread ID
+ * @returns {Object|null} Feedback object or null
+ */
+export function loadFeedback(threadId) {
+  const filePath = join(FEEDBACK_DIR, `${threadId}.json`);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Track retry count for a thread
+ * @param {string} threadId
+ * @returns {number} Current retry count
+ */
+export function getRetryCount(threadId) {
+  const feedback = loadFeedback(threadId);
+  return feedback?.retryCount || 0;
+}
+
+/**
+ * Increment retry count
+ * @param {string} threadId
+ * @returns {number} New retry count
+ */
+export function incrementRetryCount(threadId) {
+  const feedback = loadFeedback(threadId) || {};
+  feedback.retryCount = (feedback.retryCount || 0) + 1;
+  saveFeedback(threadId, feedback);
+  return feedback.retryCount;
+}
+
+/**
+ * Check if max retries exceeded
+ * @param {string} threadId
+ * @param {number} [maxRetries=5]
+ * @returns {boolean}
+ */
+export function isMaxRetriesExceeded(threadId, maxRetries = MAX_RETRIES) {
+  return getRetryCount(threadId) >= maxRetries;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function loadDefaultHooks(threadId) {
+  // Load hooks from llm-interaction.json if no hooks registered
+  const configPath = join(process.cwd(), '.morph/config/llm-interaction.json');
+  if (!existsSync(configPath)) return [];
+
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    const hookNames = config.stopHooks?.hooks || [];
+
+    return hookNames.map(name => ({
+      hookPath: `framework/hooks/agent-stop/${name}.js`,
+      config: {
+        triggers: ['on-stop', 'interval'],
+        intervalMinutes: config.stopHooks?.interval || DEFAULT_INTERVAL_MINUTES,
+        blocking: true
+      }
+    }));
+  } catch {
+    return [];
+  }
+}

package/src/lib/hops/hop-composer.js

@@ -0,0 +1,221 @@
+/**
+ * HOP Composer — Higher-Order Prompt rendering and nesting
+ *
+ * Compiles Handlebars templates for agent prompts (HOPs).
+ * Supports:
+ *   - renderHOP(templatePath, variables) → compiled prompt string
+ *   - composeHOPs(hopChain[], variables) → nested HOPs (outer wraps inner)
+ *   - listAvailableHOPs() → scan meta-prompts/ and return HOPDescriptor[]
+ *
+ * Standard HOP variables auto-injected:
+ *   FEATURE_NAME, AGENT_ID, MISSION, SPEC_SUMMARY, STANDARDS, TASKS,
+ *   DELIVERABLES, CONSTRAINTS, DATE, TIMESTAMP
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, relative, extname, basename } from 'path';
+
+const META_PROMPTS_DIR = join(process.cwd(), 'framework/templates/meta-prompts');
+const REGISTRY_PATH = join(process.cwd(), 'framework/templates/REGISTRY.json');
+
+// ============================================================================
+// Handlebars-Compatible Mini-Compiler
+// ============================================================================
+
+/**
+ * Compile a Handlebars template with variables (subset of Handlebars features)
+ * Supports: {{variable}}, {{#if condition}}...{{/if}}, {{#each array}}...{{/each}}
+ * Also supports built-in helpers: {{pascalCase}}, {{camelCase}}, {{snakeCase}}
+ *
+ * @param {string} template - Handlebars template string
+ * @param {Object} variables - Variables to inject
+ * @returns {string} Compiled template
+ */
+export function compileTemplate(template, variables) {
+  const vars = {
+    DATE: new Date().toISOString().split('T')[0],
+    TIMESTAMP: new Date().toISOString(),
+    ...injectCasedHelpers(variables),
+    ...variables
+  };
+
+  let result = template;
+
+  // 1. Process {{#if VAR}}...{{/if}} blocks
+  result = result.replace(/\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_, key, content) => {
+    return vars[key] ? content : '';
+  });
+
+  // 2. Process {{#each ARRAY}}...{{/each}} blocks
+  result = result.replace(/\{\{#each\s+(\w+)\}\}([\s\S]*?)\{\{\/each\}\}/g, (_, key, content) => {
+    const arr = vars[key];
+    if (!Array.isArray(arr)) return '';
+    return arr.map(item => {
+      const itemVars = typeof item === 'object' ? { ...vars, ...item, this: item } : { ...vars, this: item };
+      return compileTemplate(content, itemVars);
+    }).join('');
+  });
+
+  // 3. Process helper calls: {{pascalCase VARIABLE}}, {{camelCase VARIABLE}}, etc.
+  result = result.replace(/\{\{(pascalCase|camelCase|snakeCase|titleCase|pluralize)\s+(\w+)\}\}/g, (_, helper, key) => {
+    const value = String(vars[key] || '');
+    return applyHelper(helper, value);
+  });
+
+  // 4. Process simple {{VARIABLE}} substitutions
+  result = result.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    return vars[key] !== undefined ? String(vars[key]) : `{{${key}}}`;
+  });
+
+  return result;
+}
+
+function injectCasedHelpers(variables) {
+  const extras = {};
+  for (const [key, value] of Object.entries(variables)) {
+    if (typeof value === 'string') {
+      extras[`${key}_PASCAL`] = applyHelper('pascalCase', value);
+      extras[`${key}_CAMEL`] = applyHelper('camelCase', value);
+      extras[`${key}_SNAKE`] = applyHelper('snakeCase', value);
+    }
+  }
+  return extras;
+}
+
+function applyHelper(helper, value) {
+  const words = value.replace(/[-_\s]+/g, ' ').trim().split(' ');
+  switch (helper) {
+    case 'pascalCase':
+      return words.map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+    case 'camelCase':
+      return words[0].toLowerCase() + words.slice(1).map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+    case 'snakeCase':
+      return value.replace(/[-\s]+/g, '_').replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+    case 'titleCase':
+      return words.map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ');
+    case 'pluralize':
+      const last = value.slice(-1);
+      if (last === 'y') return value.slice(0, -1) + 'ies';
+      if (last === 's') return value;
+      return value + 's';
+    default:
+      return value;
+  }
+}
+
+// ============================================================================
+// HOP Rendering
+// ============================================================================
+
+/**
+ * Render a HOP template with variables
+ * @param {string} templatePath - Path to template (relative to meta-prompts/ or absolute)
+ * @param {Object} variables - Variables to inject
+ * @returns {string} Rendered prompt string
+ */
+export function renderHOP(templatePath, variables = {}) {
+  // Resolve template path
+  const paths = [
+    templatePath,
+    join(META_PROMPTS_DIR, templatePath),
+    join(META_PROMPTS_DIR, templatePath + '.md'),
+    join(process.cwd(), templatePath)
+  ];
+
+  let resolved = null;
+  for (const p of paths) {
+    if (existsSync(p)) {
+      resolved = p;
+      break;
+    }
+  }
+
+  if (!resolved) {
+    throw new Error(`HOP template not found: ${templatePath}\nSearched: ${paths.join(', ')}`);
+  }
+
+  const template = readFileSync(resolved, 'utf8');
+  return compileTemplate(template, variables);
+}
+
+/**
+ * Compose nested HOPs (outer wraps inner, variables bubble down)
+ * @param {Array} hopChain - Array of { templatePath, variables } objects (outer first)
+ * @param {Object} [sharedVariables] - Variables shared across all HOPs
+ * @returns {string} Composed prompt string
+ */
+export function composeHOPs(hopChain, sharedVariables = {}) {
+  if (!hopChain || hopChain.length === 0) {
+    throw new Error('hopChain must be a non-empty array');
+  }
+
+  if (hopChain.length === 1) {
+    return renderHOP(hopChain[0].templatePath, { ...sharedVariables, ...hopChain[0].variables });
+  }
+
+  // Render inner HOPs first, then wrap with outer
+  let innerContent = '';
+  for (let i = hopChain.length - 1; i >= 1; i--) {
+    const hop = hopChain[i];
+    const vars = { ...sharedVariables, ...hop.variables, INNER_PROMPT: innerContent };
+    innerContent = renderHOP(hop.templatePath, vars);
+  }
+
+  // Render outermost HOP with inner content
+  const outerHop = hopChain[0];
+  return renderHOP(outerHop.templatePath, {
+    ...sharedVariables,
+    ...outerHop.variables,
+    INNER_PROMPT: innerContent
+  });
+}
+
+// ============================================================================
+// HOP Discovery
+// ============================================================================
+
+/**
+ * List all available HOPs from the meta-prompts directory
+ * @returns {Array} Array of HOPDescriptor objects
+ */
+export function listAvailableHOPs() {
+  if (!existsSync(META_PROMPTS_DIR)) return [];
+
+  const hops = [];
+  scanDir(META_PROMPTS_DIR, META_PROMPTS_DIR, hops);
+  return hops;
+}
+
+function scanDir(dir, baseDir, hops) {
+  if (!existsSync(dir)) return;
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      scanDir(fullPath, baseDir, hops);
+    } else if (entry.name.endsWith('.md') || entry.name.endsWith('.hbs')) {
+      const relPath = relative(baseDir, fullPath);
+      const content = readFileSync(fullPath, 'utf8');
+      const firstLine = content.split('\n')[0] || '';
+      const description = firstLine.startsWith('#')
+        ? firstLine.replace(/^#+\s*/, '')
+        : 'Higher-Order Prompt template';
+
+      // Extract variables from template
+      const variables = [...new Set(
+        (content.match(/\{\{(\w+)\}\}/g) || [])
+          .map(m => m.replace(/\{\{|\}\}/g, ''))
+          .filter(v => !['if', 'each', 'this', 'else', 'pascalCase', 'camelCase', 'snakeCase', 'titleCase', 'pluralize'].includes(v))
+      )];
+
+      hops.push({
+        id: relPath.replace(/\\/g, '/').replace(/\.(md|hbs)$/, ''),
+        path: fullPath,
+        relativePath: relPath.replace(/\\/g, '/'),
+        description,
+        variables,
+        category: relPath.split(/[\\/]/)[0]
+      });
+    }
+  }
+}