@hailer/mcp 1.0.28 → 1.1.2

package/.claude/hooks/_utils.cjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * Shared utilities for Claude Code hooks
+ *
+ * Usage:
+ *   const { isYoloMode, readStdin, safeJsonParse, outputAllow } = require('./_utils.cjs');
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Cache yolo mode per-process since it doesn't change within a single hook execution
+let _yoloCache;
+
+/**
+ * Check if yolo mode is active
+ * @returns {boolean}
+ */
+function isYoloMode() {
+  if (_yoloCache !== undefined) return _yoloCache;
+  try {
+    const statePath = path.join(
+      process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+      '.claude',
+      'yolo-state.json'
+    );
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    _yoloCache = state.mode === 'yolo';
+    return _yoloCache;
+  } catch {
+    _yoloCache = false;
+    return false;
+  }
+}
+
+/**
+ * Read stdin safely with TTY check (async)
+ * @returns {Promise<string>} The stdin content or empty string if TTY
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) {
+      resolve('');
+      return;
+    }
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => data += chunk);
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+/**
+ * Read stdin synchronously with TTY check
+ * @returns {string} The stdin content or empty string if TTY
+ */
+function readStdinSync() {
+  if (process.stdin.isTTY) {
+    return '';
+  }
+  return fs.readFileSync(0, 'utf8');
+}
+
+/**
+ * Parse JSON safely, return null on failure
+ * @param {string} str - JSON string to parse
+ * @param {string} hookName - Hook name for error logging
+ * @returns {object|null}
+ */
+function safeJsonParse(str, hookName = 'hook') {
+  try {
+    return JSON.parse(str);
+  } catch (e) {
+    console.error(`[${hookName}] Failed to parse JSON: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Output allow decision and exit
+ * @param {string} [message] - Optional message to log to stderr
+ */
+function outputAllow(message) {
+  if (message) {
+    console.error(message);
+  }
+  console.log(JSON.stringify({ decision: 'allow' }));
+  process.exit(0);
+}
+
+/**
+ * Output deny decision and exit
+ * @param {string} reason - Reason for denial
+ */
+function outputDeny(reason) {
+  console.log(JSON.stringify({
+    permissionDecision: 'deny',
+    permissionDecisionReason: reason
+  }));
+  process.exit(0);
+}
+
+/**
+ * Get project directory from environment
+ * @returns {string}
+ */
+function getProjectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Check if a path exists
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  isYoloMode,
+  readStdin,
+  readStdinSync,
+  safeJsonParse,
+  outputAllow,
+  outputDeny,
+  getProjectDir,
+  fileExists
+};

package/.claude/hooks/agent-failure-detector.cjs

@@ -22,20 +22,42 @@
  * <behavior>
  * 1. Detects failure patterns in agent response
  * 2. Categorizes error type
- * 3. Tracks per-agent failure count
- * 4. After 2+ failures, suggests fix via AskUserQuestion
- * 5. Recommends spawning ada to create skill or update agent
+ * 3. Logs to global failures.log
+ * 4. Auto-spawns Ada on first actionable failure to create skill or update agent
  * </behavior>
  *
  * <tracker-file>/tmp/.claude-agent-failures.json</tracker-file>
+ * <log-file>$CLAUDE_PROJECT_DIR/inbox/failures.log</log-file>
  */
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const TRACKER_FILE = path.join(os.tmpdir(), '.claude-agent-failures.json');
-const FAILURE_THRESHOLD = 2;
+// Skip in yolo mode
+try {
+  const statePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.claude', 'yolo-state.json');
+  const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  if (state.mode === 'yolo') process.exit(0);
+} catch (e) {
+  // ENOENT is expected when not in yolo mode - only warn on unexpected errors
+  if (e.code !== 'ENOENT' && !e.message.includes('Unexpected')) {
+    console.error(`[agent-failure-detector] Warning: ${e.message}`);
+  }
+}
+
+const TEMP_DIR = os.tmpdir();
+const TRACKER_FILE = path.join(TEMP_DIR, '.claude-agent-failures.json');
+const GLOBAL_LOG_FILE = path.join(
+  process.env.HAILER_INBOX_DIR || path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), 'inbox'),
+  'failures.log'
+);
+const FAILURE_THRESHOLD = 1;  // Auto-spawn Ada on first failure
+
+// Skip if stdin is TTY (no piped input)
+if (process.stdin.isTTY) {
+  process.exit(0);
+}
 
 let input = '';
 process.stdin.setEncoding('utf8');
@@ -44,7 +66,8 @@ process.stdin.on('end', () => {
   try {
     const data = JSON.parse(input);
     processHook(data);
-  } catch {
+  } catch (e) {
+    console.error(`[agent-failure-detector] Failed to parse input: ${e.message}`);
     process.exit(0);
   }
 });
@@ -54,7 +77,9 @@ function loadTracker() {
     if (fs.existsSync(TRACKER_FILE)) {
       return JSON.parse(fs.readFileSync(TRACKER_FILE, 'utf8'));
     }
-  } catch {}
+  } catch (e) {
+    console.error(`[agent-failure-detector] Warning: ${e.message}`);
+  }
   return { failures: {}, prompted: {}, errorTypes: {} };
 }
 
@@ -62,6 +87,28 @@ function saveTracker(tracker) {
   fs.writeFileSync(TRACKER_FILE, JSON.stringify(tracker, null, 2));
 }
 
+/**
+ * Log failure to global file for persistent tracking
+ */
+function logFailureToGlobal(agentName, errorInfo, errorMessage, projectDir) {
+  try {
+    const timestamp = new Date().toISOString();
+    const project = projectDir ? path.basename(projectDir) : 'unknown';
+    const logEntry = `[${timestamp}] ${agentName} | ${errorInfo.category} | ${project} | ${errorMessage}\n`;
+
+    // Ensure ~/.claude directory exists
+    const claudeDir = path.dirname(GLOBAL_LOG_FILE);
+    if (!fs.existsSync(claudeDir)) {
+      fs.mkdirSync(claudeDir, { recursive: true });
+    }
+
+    fs.appendFileSync(GLOBAL_LOG_FILE, logEntry);
+  } catch (err) {
+    // Don't fail the hook if logging fails
+    console.error(`[agent-failure-detector] Could not write to log: ${err.message}`);
+  }
+}
+
 // Error categorization - determines fix type
 const ERROR_CATEGORIES = {
   // API/Schema errors -> Create skill (reusable knowledge)
@@ -79,7 +126,23 @@ const ERROR_CATEGORIES = {
       'activitylink',
       'workflow.*not found',
       'phase.*not found',
-      'field.*not found'
+      'field.*not found',
+      'functionvariables',
+      'functionfield',
+      'namefunction',
+      'wrong.*type',
+      'expected.*got',
+      'cannot read prop',
+      'undefined.*null',
+      'processid',
+      'phaseid',
+      'fieldid',
+      'workflowid',
+      'insight.*error',
+      'template.*error',
+      'pdfmake',
+      'mcp.*error',
+      'tool.*failed'
     ],
     suggestion: 'Create a skill documenting the correct pattern',
     action: 'create_skill'
@@ -95,7 +158,18 @@ const ERROR_CATEGORIES = {
       'didn\'t check',
       'missing context',
       'needs to first',
-      'order of operations'
+      'order of operations',
+      'wrong agent',
+      'not my responsibility',
+      'outside.*scope',
+      'cannot handle',
+      'don\'t have.*tool',
+      'need.*first',
+      'pull.*before',
+      'push.*after',
+      'didn\'t read',
+      'assumed',
+      'skipped'
     ],
     suggestion: 'Update agent definition with better instructions',
     action: 'update_agent'
@@ -107,7 +181,16 @@ const ERROR_CATEGORIES = {
       'unauthorized',
       'access denied',
       'not allowed',
-      'admin required'
+      'admin required',
+      '401',
+      '403',
+      'oauth',
+      'token.*expired',
+      'token.*invalid',
+      'authentication_error',
+      'credentials',
+      'login failed',
+      'session expired'
     ],
     suggestion: 'User permission issue - not an agent problem',
     action: 'ignore'
@@ -120,7 +203,18 @@ const ERROR_CATEGORIES = {
       'network',
       'unavailable',
       'try again',
-      'rate limit'
+      'rate limit',
+      'econnrefused',
+      'enotfound',
+      'socket',
+      '500',
+      '502',
+      '503',
+      '504',
+      'server error',
+      'temporarily',
+      'overloaded',
+      'busy'
     ],
     suggestion: 'Transient error - retry may work',
     action: 'ignore'
@@ -174,22 +268,36 @@ function detectFailure(responseText) {
 }
 
 function extractErrorMessage(responseText) {
-  // Try to extract meaningful error message
+  // Try to extract meaningful error message - more patterns
   const patterns = [
     /"error":\s*"([^"]+)"/i,
     /"message":\s*"([^"]+)"/i,
+    /"summary":\s*"([^"]+)"/i,
+    /"reason":\s*"([^"]+)"/i,
     /Error:\s*([^\n]+)/i,
-    /failed to ([^\n.]+)/i
+    /failed to ([^\n.]+)/i,
+    /could not ([^\n.]+)/i,
+    /unable to ([^\n.]+)/i,
+    /invalid ([^\n.]+)/i,
+    /missing ([^\n.]+)/i,
+    /\d{3}\s*[{"]([^"}\n]+)/i,  // HTTP status followed by message
+    /"status":\s*"error"[^}]*"([^"]+)"/i
   ];
 
   for (const pattern of patterns) {
     const match = responseText.match(pattern);
-    if (match) {
-      return match[1].substring(0, 100); // Limit length
+    if (match && match[1] && match[1].trim().length > 3) {
+      return match[1].trim().substring(0, 150); // Limit length
     }
   }
 
-  return 'Unknown error';
+  // Last resort: grab first 100 chars of anything that looks like an error
+  const errorSnippet = responseText.match(/error[^a-z]*(.{10,100})/i);
+  if (errorSnippet) {
+    return errorSnippet[1].trim().substring(0, 100);
+  }
+
+  return 'Unknown error - check agent output';
 }
 
 function processHook(data) {
@@ -221,7 +329,11 @@ function processHook(data) {
     process.exit(0);
   }
 
-  // Track the failure with category
+  // Log to global file for persistent tracking
+  const projectDir = process.env.CLAUDE_PROJECT_DIR;
+  logFailureToGlobal(agentName, errorInfo, errorMessage, projectDir);
+
+  // Track the failure with category (session-level tracking for prompts)
   const tracker = loadTracker();
   const key = `${agentName}:${errorInfo.category}`;
   tracker.failures[key] = (tracker.failures[key] || 0) + 1;
@@ -234,76 +346,49 @@ function processHook(data) {
     tracker.prompted[key] = true;
     saveTracker(tracker);
 
-    // Build suggestion based on category
-    let fixOptions;
-    let recommendation;
-
-    if (errorInfo.action === 'create_skill') {
-      recommendation = `📚 RECOMMENDED: Create a skill to document this pattern`;
-      fixOptions = [
-        { label: 'Create skill', description: `Ada creates docs/skills/ entry for ${errorInfo.matchedPattern || 'this pattern'}` },
-        { label: 'Update agent instead', description: `Add knowledge directly to ${agentName}'s definition` },
-        { label: 'Ignore', description: 'Continue without changes' }
-      ];
-    } else if (errorInfo.action === 'update_agent') {
-      recommendation = `🤖 RECOMMENDED: Update ${agentName}'s agent definition`;
-      fixOptions = [
-        { label: 'Update agent', description: `Ada adds better instructions to ${agentName}.md` },
-        { label: 'Create skill instead', description: 'Document as reusable skill for all agents' },
-        { label: 'Ignore', description: 'Continue without changes' }
-      ];
-    } else {
-      recommendation = `🔍 ANALYZE: Let Ada determine the best fix`;
-      fixOptions = [
-        { label: 'Let Ada analyze', description: 'Ada will determine if skill or agent update is better' },
-        { label: 'Ignore', description: 'Continue without changes' }
-      ];
+    // Determine action type
+    let actionType = errorInfo.action;
+    if (actionType === 'analyze') {
+      actionType = 'create_skill';  // Default to skill creation
     }
 
+    // Sanitize error message to prevent injection via temp file
+    const safeErrorMessage = errorMessage
+      .replace(/[`$\\]/g, '')
+      .substring(0, 500);
+
+    // Build the Ada task prompt
+    const adaPromptObj = {
+      task: actionType,
+      agent: agentName,
+      error: safeErrorMessage,
+      category: errorInfo.category,
+      pattern: errorInfo.matchedPattern || 'unknown'
+    };
+
+    // SECURITY: Write prompt to temp file to avoid shell injection
+    // Never embed user-controlled strings directly in shell commands
+    const tmpDir = os.tmpdir();
+    const tmpFile = path.join(tmpDir, `ada-prompt-${Date.now()}-${process.pid}.json`);
+    fs.writeFileSync(tmpFile, JSON.stringify(adaPromptObj, null, 2));
+
+    // AUTO-SPAWN Ada on first actionable failure
+    // The orchestrator reads the temp file path and handles the Task call safely
     const output = `
-${'='.repeat(60)}
-🔧 AGENT IMPROVEMENT SUGGESTION
-${'='.repeat(60)}
+<user-prompt-submit-hook>
+🤖 AUTO-SPAWNING ADA - ${errorInfo.category} failure detected
 
-Agent "${agentName}" has failed ${failureCount} times with similar errors.
+Agent: ${agentName}
+Action: ${actionType === 'create_skill' ? 'Creating skill' : 'Updating agent'}
 
-**Error type:** ${errorInfo.category}
-**Error:** ${errorMessage}
-**Pattern:** ${errorInfo.matchedPattern || 'general failure'}
-
-${recommendation}
-
-USE THIS AskUserQuestion CALL:
-
-\`\`\`json
-{
-  "questions": [{
-    "question": "${agentName} failed ${failureCount}x (${errorInfo.category}). How should Ada fix this?",
-    "header": "Fix type",
-    "options": ${JSON.stringify(fixOptions)},
-    "multiSelect": false
-  }]
-}
-\`\`\`
-
-After user responds, invoke Ada with context:
-\`\`\`
-Task(subagent_type="ada", prompt=\`{
-  "task": "${errorInfo.action === 'create_skill' ? 'create_skill' : 'update_agent'}",
-  "context": {
-    "agent": "${agentName}",
-    "error_type": "${errorInfo.category}",
-    "error_message": "${errorMessage.replace(/"/g, '\\"')}",
-    "failure_count": ${failureCount}
-  },
-  "output": ["action_taken", "file_path"]
-}\`)
-\`\`\`
+Ada prompt saved to: ${tmpFile}
 
-${'='.repeat(60)}
+ORCHESTRATOR: Read the JSON file above and call:
+Task(subagent_type="agent-ada-skill-builder", prompt=<contents of ${tmpFile}>)
+</user-prompt-submit-hook>
 `;
 
-    console.error(output);
+    console.log(output);
   }
 
   process.exit(0);

package/.claude/hooks/agent-usage-logger.cjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * <hook-name>agent-usage-logger</hook-name>
+ *
+ * <purpose>
+ * Logs every agent call for analytics - which agents are used, success/fail rates, duration.
+ * </purpose>
+ *
+ * <triggers>
+ * - PostToolUse on Task
+ * </triggers>
+ *
+ * <log-file>$CLAUDE_PROJECT_DIR/inbox/usage.jsonl</log-file>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const LOG_FILE = path.join(
+  process.env.HAILER_INBOX_DIR || path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), 'inbox'),
+  'usage.jsonl'
+);
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    processHook(data);
+  } catch (e) {
+    console.error(`[agent-usage-logger] Failed to parse input: ${e.message}`);
+    process.exit(0);
+  }
+});
+
+// Cache directory creation state to avoid repeated mkdirSync calls
+let _dirCreated = false;
+
+function detectStatus(responseText) {
+  // Try to parse as JSON first for reliable status detection
+  try {
+    const parsed = JSON.parse(responseText);
+    if (parsed.status === 'success' || parsed.status === 'ready_to_push') {
+      return 'success';
+    }
+    if (parsed.status === 'error') {
+      return 'error';
+    }
+  } catch (e) {
+    // Not valid JSON, fall back to string matching
+  }
+
+  // Fallback: string matching for non-JSON responses
+  const lower = responseText.toLowerCase();
+
+  if (lower.includes('"status":"success"') || lower.includes('"status": "success"')) {
+    return 'success';
+  }
+  if (lower.includes('"status":"ready_to_push"') || lower.includes('"status": "ready_to_push"')) {
+    return 'success';
+  }
+  if (lower.includes('"status":"error"') || lower.includes('"status": "error"')) {
+    return 'error';
+  }
+  if (lower.includes('failed') || lower.includes('error:') || lower.includes('could not')) {
+    return 'error';
+  }
+
+  return 'unknown';
+}
+
+function processHook(data) {
+  const { tool_name, tool_input, tool_response } = data;
+
+  if (tool_name !== 'Task') {
+    process.exit(0);
+  }
+
+  const agentName = tool_input?.subagent_type || 'unknown';
+  const description = tool_input?.description || '';
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const project = path.basename(projectDir);
+
+  const responseText = typeof tool_response === 'string'
+    ? tool_response
+    : JSON.stringify(tool_response || '');
+
+  const status = detectStatus(responseText);
+
+  const entry = {
+    ts: new Date().toISOString(),
+    agent: agentName,
+    status,
+    project,
+    description: (description || '').substring(0, 50)
+  };
+
+  try {
+    // Ensure directory exists (recursive: true is idempotent, no TOCTOU race)
+    if (!_dirCreated) {
+      const claudeDir = path.dirname(LOG_FILE);
+      fs.mkdirSync(claudeDir, { recursive: true });
+      _dirCreated = true;
+    }
+
+    fs.appendFileSync(LOG_FILE, JSON.stringify(entry) + '\n');
+  } catch (err) {
+    // Don't fail the hook if logging fails
+    console.error(`[agent-usage-logger] Could not write: ${err.message}`);
+  }
+
+  process.exit(0);
+}
+
+// CLI: Show recent usage
+if (process.argv[2] === '--recent' || process.argv[2] === '-r') {
+  const limit = parseInt(process.argv[3]) || 20;
+
+  if (!fs.existsSync(LOG_FILE)) {
+    console.log('No usage data yet');
+    process.exit(0);
+  }
+
+  const lines = fs.readFileSync(LOG_FILE, 'utf8').trim().split('\n').filter(Boolean);
+  const recent = lines.slice(-limit);
+
+  console.log(`Last ${recent.length} agent calls:\n`);
+  for (const line of recent) {
+    try {
+      const entry = JSON.parse(line);
+      const status = entry.status === 'success' ? '✓' : entry.status === 'error' ? '✗' : '?';
+      const time = entry.ts.split('T')[1].split('.')[0];
+      console.log(`${time} ${status} ${entry.agent.padEnd(20)} ${entry.project}`);
+    } catch {}
+  }
+  process.exit(0);
+}
+
+// CLI: Show stats
+if (process.argv[2] === '--stats' || process.argv[2] === '-s') {
+  if (!fs.existsSync(LOG_FILE)) {
+    console.log('No usage data yet');
+    process.exit(0);
+  }
+
+  const lines = fs.readFileSync(LOG_FILE, 'utf8').trim().split('\n').filter(Boolean);
+  const stats = {};
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (!stats[entry.agent]) {
+        stats[entry.agent] = { total: 0, success: 0, error: 0 };
+      }
+      stats[entry.agent].total++;
+      if (entry.status === 'success') stats[entry.agent].success++;
+      if (entry.status === 'error') stats[entry.agent].error++;
+    } catch {}
+  }
+
+  console.log('Agent Usage Stats:\n');
+  console.log('Agent'.padEnd(25) + 'Total'.padEnd(8) + 'Success'.padEnd(10) + 'Errors');
+  console.log('-'.repeat(50));
+
+  const sorted = Object.entries(stats).sort((a, b) => b[1].total - a[1].total);
+  for (const [agent, s] of sorted) {
+    const rate = s.total > 0 ? Math.round((s.success / s.total) * 100) : 0;
+    console.log(`${agent.padEnd(25)}${String(s.total).padEnd(8)}${(s.success + ' (' + rate + '%)').padEnd(10)}${s.error}`);
+  }
+
+  console.log('-'.repeat(50));
+  console.log(`Total: ${lines.length} calls`);
+  process.exit(0);
+}
+
+// CLI: Clear log
+if (process.argv[2] === '--clear') {
+  if (fs.existsSync(LOG_FILE)) {
+    fs.unlinkSync(LOG_FILE);
+    console.log('✓ Usage log cleared');
+  } else {
+    console.log('No log file to clear');
+  }
+  process.exit(0);
+}
+
+// CLI: Help
+if (process.argv[2] === '--help' || process.argv[2] === '-h') {
+  console.log(`
+Agent Usage Logger - Track agent calls
+
+Usage:
+  node agent-usage-logger.cjs --recent [N]   Show last N calls (default 20)
+  node agent-usage-logger.cjs --stats        Show usage statistics
+  node agent-usage-logger.cjs --clear        Clear the log
+  node agent-usage-logger.cjs --help         Show this help
+
+Log file: ${LOG_FILE}
+`);
+  process.exit(0);
+}