ninja-terminals 2.0.0 → 2.1.0

package/CLAUDE.md

@@ -54,25 +54,10 @@ These status lines are CRITICAL — the orchestrator parses them to know your st
 - The orchestrator relays between terminals
 
 ## MCP Tools
-You have access to 170+ MCP tools. Use them proactively:
-- **postforme**: Video rendering, social publishing, Meta ads, content management, brand profiles, asset management, insights/analytics
-- **studychat**: RAG knowledge base, DMs, C2C messaging, document upload/query
-- **chrome-devtools**: Browser automation — navigate, click, type, screenshot, forms, network monitoring
-- **gmail**: Search emails, read messages, download attachments
-- **netlify-billing / render-billing**: Deployment status, billing, service health
-- **builder-pro**: Code review, security scan, auto-fix, architecture validation
-- **gkchatty**: Knowledge base queries, uploads — DO NOT USE unless explicitly instructed
-
-### PostForMe Publishing — Use the Right Tool
-| Content Type | Correct Tool | Wrong Tool (will fail) |
-|---|---|---|
-| Video → IG Reel | `publish_meta(contentId, platform: "instagram")` | — |
-| Video → FB | `publish_meta(contentId, platform: "facebook")` | — |
-| Video → Story | `publish_story(contentId, imageUrl/videoUrl)` | publish_meta |
-| Carousel (multi-image) | `publish_carousel(imageUrls: [...], caption)` | publish_meta |
+Ninja Terminals works with any MCP tools you have configured. The orchestrator and workers will automatically detect and use your installed MCP servers.
 
 ### Tool Selection Priority
-1. Check the tool list first — verify it accepts the parameters you need
+1. Check your available tool list first — verify it accepts the parameters you need
 2. Use the most direct tool available (MCP > browser automation > manual)
 3. If an MCP tool exists for the task, prefer it over browser-driving
 4. Use browser automation for websites without an MCP/API

package/cli.js

@@ -33,13 +33,23 @@ OPTIONS
   --port        <number>   Port to listen on          (default: 3300)
   --terminals   <number>   Number of terminals to spawn (default: 4)
   --cwd         <path>     Working directory for terminals (default: current dir)
+  --token       <jwt>      Auth token for Pro users / CI (skips browser login)
+  --offline                Offline mode for Pro users (skips backend validation)
   --version, -v            Print version and exit
   --help,    -h            Show this help message
 
+AUTHENTICATION
+  Pro users can authenticate via:
+    1. Browser login (default) - sign in at the web UI
+    2. --token flag - pass JWT directly (useful for CI/scripts)
+    3. --offline flag - skip validation (requires downloaded Pro package)
+
 EXAMPLES
   npx ninja-terminals
   npx ninja-terminals --port 3301 --terminals 2
   npx ninja-terminals --cwd /path/to/my-project
+  npx ninja-terminals --token eyJhbGciOiJIUzI1NiIs...
+  npx ninja-terminals --offline
 `);
   process.exit(0);
 }
@@ -52,6 +62,8 @@ if (hasFlag('--version') || hasFlag('-v')) {
 const port      = parseInt(getArg('--port',      '3300'),  10);
 const terminals = parseInt(getArg('--terminals', '4'),     10);
 const cwd       = getArg('--cwd', process.cwd());
+const token     = getArg('--token', null);
+const offline   = hasFlag('--offline');
 
 if (isNaN(port) || port < 1 || port > 65535) {
   console.error(`Error: --port must be a number between 1 and 65535`);
@@ -65,6 +77,8 @@ if (isNaN(terminals) || terminals < 1 || terminals > 16) {
 
 // ── Startup banner ───────────────────────────────────────────
 
+const authMode = offline ? 'offline' : (token ? 'token' : 'browser');
+
 console.log(`
 ╔═══════════════════════════════════════╗
 ║          NINJA TERMINALS v${pkg.version}          ║
@@ -73,6 +87,7 @@ console.log(`
 ║  Port       : ${String(port).padEnd(24)} ║
 ║  Terminals  : ${String(terminals).padEnd(24)} ║
 ║  CWD        : ${cwd.length > 24 ? '...' + cwd.slice(-21) : cwd.padEnd(24)} ║
+║  Auth       : ${authMode.padEnd(24)} ║
 ╚═══════════════════════════════════════╝
 `);
 
@@ -84,6 +99,14 @@ process.env.PORT               = String(port);
 process.env.DEFAULT_TERMINALS  = String(terminals);
 process.env.DEFAULT_CWD        = cwd;
 
+// Auth env vars
+if (token) {
+  process.env.NINJA_AUTH_TOKEN = token;
+}
+if (offline) {
+  process.env.NINJA_OFFLINE = '1';
+}
+
 // ── Auto-open browser ────────────────────────────────────────
 
 function openBrowser(url) {

package/lib/auth.js

@@ -0,0 +1,195 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Auth module — Token validation and session middleware for Ninja Terminals
+// ---------------------------------------------------------------------------
+
+const BACKEND_URL = process.env.NINJA_BACKEND_URL || 'https://emtchat-backend.onrender.com';
+
+// In-memory cache for validated sessions (token -> session data)
+// Used as fallback when network is unavailable
+const validationCache = new Map();
+
+/**
+ * Validate a token against the backend.
+ *
+ * @param {string} token - Bearer token to validate
+ * @returns {Promise<{valid: boolean, tier: string, terminalsMax: number, features: string[]}|null>}
+ */
+async function validateToken(token) {
+  if (!token) return null;
+
+  try {
+    const response = await fetch(`${BACKEND_URL}/api/ninja/validate`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(10000), // 10s timeout
+    });
+
+    if (!response.ok) {
+      // Token invalid or expired
+      return null;
+    }
+
+    const data = await response.json();
+
+    // Cache the result
+    const result = {
+      valid: true,
+      tier: data.tier || 'free',
+      terminalsMax: data.terminalsMax || 1,
+      features: data.features || [],
+      validatedAt: Date.now(),
+    };
+
+    validationCache.set(token, result);
+    return result;
+
+  } catch (err) {
+    // Network error — check cache for fallback
+    const cached = validationCache.get(token);
+    if (cached && cached.valid) {
+      console.warn(`[auth] Network error validating token, using cache: ${err.message}`);
+      return cached;
+    }
+    return null;
+  }
+}
+
+/**
+ * Create Express middleware that validates Authorization Bearer tokens.
+ *
+ * @param {Map} sessionCache - Shared session cache (token -> session data)
+ * @returns {import('express').RequestHandler}
+ */
+function createAuthMiddleware(sessionCache) {
+  return async function authMiddleware(req, res, next) {
+    // Extract Bearer token from Authorization header
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return res.status(401).json({ error: 'Missing or invalid Authorization header' });
+    }
+
+    const token = authHeader.slice(7); // Remove 'Bearer ' prefix
+    if (!token) {
+      return res.status(401).json({ error: 'Empty token' });
+    }
+
+    // Check session cache first
+    const cached = sessionCache.get(token);
+    const now = Date.now();
+    const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+    if (cached && (now - cached.validatedAt) < CACHE_TTL) {
+      // Cache hit and fresh
+      req.ninjaUser = {
+        tier: cached.tier,
+        terminalsMax: cached.terminalsMax,
+        features: cached.features,
+        token,
+      };
+      return next();
+    }
+
+    // Cache miss or stale — validate against backend
+    const result = await validateToken(token);
+
+    if (!result || !result.valid) {
+      return res.status(401).json({ error: 'Invalid or expired token' });
+    }
+
+    // Update cache
+    sessionCache.set(token, {
+      tier: result.tier,
+      terminalsMax: result.terminalsMax,
+      features: result.features,
+      validatedAt: now,
+    });
+
+    req.ninjaUser = {
+      tier: result.tier,
+      terminalsMax: result.terminalsMax,
+      features: result.features,
+      token,
+    };
+
+    next();
+  };
+}
+
+/**
+ * WebSocket token validation for upgrade requests.
+ *
+ * @param {string} token - Token from query param
+ * @param {Map} sessionCache - Shared session cache
+ * @returns {Promise<{valid: boolean, tier?: string, terminalsMax?: number, features?: string[]}>}
+ */
+async function validateWebSocketToken(token, sessionCache) {
+  if (!token) {
+    return { valid: false };
+  }
+
+  // Check session cache first
+  const cached = sessionCache.get(token);
+  const now = Date.now();
+  const CACHE_TTL = 5 * 60 * 1000;
+
+  if (cached && (now - cached.validatedAt) < CACHE_TTL) {
+    return { valid: true, ...cached };
+  }
+
+  // Validate against backend
+  const result = await validateToken(token);
+  if (!result || !result.valid) {
+    return { valid: false };
+  }
+
+  // Update cache
+  sessionCache.set(token, {
+    tier: result.tier,
+    terminalsMax: result.terminalsMax,
+    features: result.features,
+    validatedAt: now,
+  });
+
+  return { valid: true, ...result };
+}
+
+/**
+ * Start heartbeat that re-validates stored sessions.
+ * If a session becomes invalid, the callback is invoked to clean up.
+ *
+ * @param {Map} sessionCache - Shared session cache
+ * @param {(token: string) => void} onInvalid - Callback when a session becomes invalid
+ * @param {number} [intervalMs=300000] - Heartbeat interval (default 5 min)
+ * @returns {NodeJS.Timeout} Interval handle
+ */
+function startSessionHeartbeat(sessionCache, onInvalid, intervalMs = 5 * 60 * 1000) {
+  return setInterval(async () => {
+    for (const [token, session] of sessionCache.entries()) {
+      const result = await validateToken(token);
+      if (!result || !result.valid) {
+        console.log(`[auth] Session invalidated during heartbeat`);
+        sessionCache.delete(token);
+        onInvalid(token);
+      } else {
+        // Update cached data
+        session.tier = result.tier;
+        session.terminalsMax = result.terminalsMax;
+        session.features = result.features;
+        session.validatedAt = Date.now();
+      }
+    }
+  }, intervalMs);
+}
+
+module.exports = {
+  validateToken,
+  createAuthMiddleware,
+  validateWebSocketToken,
+  startSessionHeartbeat,
+  BACKEND_URL,
+};

package/lib/hypothesis-validator.js

@@ -0,0 +1,346 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parsePlaybooks } = require('./playbook-tracker');
+const { SUMMARIES_PATH } = require('./analyze-session');
+
+const STATE_PATH = path.join(__dirname, '..', 'orchestrator', 'metrics', 'hypothesis-state.json');
+
+// Decision thresholds from Phase 4 spec
+const MIN_TEST_SESSIONS = 3;
+const IMPROVEMENT_THRESHOLD = 0.10; // 10%
+
+/**
+ * Extract metric targets from hypothesis text.
+ * Maps hypothesis claims to measurable metrics.
+ * @param {string} hypothesisText - The full hypothesis section text
+ * @returns {object} { type: 'tool'|'session'|'pattern', target: string, metric: string }
+ */
+function extractMetricTarget(hypothesisText) {
+  const text = hypothesisText.toLowerCase();
+
+  // Tool-specific hypotheses: "Edit has C rating", "prefer Write over Edit", "Glob is reliable"
+  const toolPatterns = [
+    { regex: /\b(edit|write|read|bash|glob|grep|agent)\b.*\b(rating|reliable|failure|prefer)/i, metric: 'success_rate' },
+    { regex: /prefer\s+(\w+)\s+over\s+(\w+)/i, metric: 'success_rate' },
+    { regex: /\b(\w+)\s+has\s+[a-s]\s+rating/i, metric: 'success_rate' },
+  ];
+
+  for (const pattern of toolPatterns) {
+    const match = hypothesisText.match(pattern.regex);
+    if (match) {
+      // Extract the tool name (capitalize first letter)
+      const toolName = match[1].charAt(0).toUpperCase() + match[1].slice(1).toLowerCase();
+      return { type: 'tool', target: toolName, metric: pattern.metric };
+    }
+  }
+
+  // Session-level hypotheses: "staggered dispatch", "session time"
+  if (text.includes('staggered') || text.includes('dispatch') || text.includes('session time')) {
+    return { type: 'session', target: 'duration', metric: 'duration_min' };
+  }
+
+  // Default: overall tool success rate
+  return { type: 'aggregate', target: 'all_tools', metric: 'success_rate' };
+}
+
+/**
+ * Load all session summaries from NDJSON file.
+ * @param {string} summariesPath
+ * @returns {Array<object>} Parsed session summaries
+ */
+function loadSummaries(summariesPath) {
+  const filePath = summariesPath || SUMMARIES_PATH;
+  if (!fs.existsSync(filePath)) return [];
+
+  const lines = fs.readFileSync(filePath, 'utf8').trim().split('\n').filter(Boolean);
+  const summaries = [];
+
+  for (const line of lines) {
+    try {
+      summaries.push(JSON.parse(line));
+    } catch { /* skip malformed */ }
+  }
+
+  // Deduplicate by session_id (keep latest)
+  const seen = new Map();
+  for (const s of summaries) {
+    seen.set(s.session_id, s);
+  }
+
+  return Array.from(seen.values());
+}
+
+/**
+ * Load or initialize hypothesis tracking state.
+ * Tracks when each hypothesis was first observed (by session count).
+ * @returns {object} { hypotheses: { [name]: { firstSeenAt: number, sessionCount: number } } }
+ */
+function loadState() {
+  if (!fs.existsSync(STATE_PATH)) {
+    return { hypotheses: {} };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return { hypotheses: {} };
+  }
+}
+
+/**
+ * Save hypothesis tracking state.
+ * @param {object} state
+ */
+function saveState(state) {
+  const dir = path.dirname(STATE_PATH);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8');
+}
+
+/**
+ * Compute aggregate metrics for a set of sessions.
+ * @param {Array<object>} sessions
+ * @param {object} target - { type, target, metric }
+ * @returns {object} { value: number, sampleSize: number }
+ */
+function computeMetric(sessions, target) {
+  if (sessions.length === 0) {
+    return { value: null, sampleSize: 0 };
+  }
+
+  if (target.type === 'tool') {
+    // Aggregate tool-specific metrics
+    let totalInvocations = 0;
+    let totalSuccesses = 0;
+
+    for (const s of sessions) {
+      const toolData = s.tools?.[target.target];
+      if (toolData) {
+        totalInvocations += toolData.invocations || 0;
+        totalSuccesses += toolData.successes || 0;
+      }
+    }
+
+    if (totalInvocations === 0) {
+      return { value: null, sampleSize: 0 };
+    }
+
+    return {
+      value: totalSuccesses / totalInvocations,
+      sampleSize: totalInvocations,
+    };
+  }
+
+  if (target.type === 'session') {
+    // Session-level metrics (e.g., duration)
+    const values = sessions.map(s => s[target.metric]).filter(v => v != null && v > 0);
+    if (values.length === 0) {
+      return { value: null, sampleSize: 0 };
+    }
+
+    const avg = values.reduce((a, b) => a + b, 0) / values.length;
+    return { value: avg, sampleSize: values.length };
+  }
+
+  // Aggregate: all tools combined
+  let totalInvocations = 0;
+  let totalSuccesses = 0;
+
+  for (const s of sessions) {
+    for (const toolData of Object.values(s.tools || {})) {
+      totalInvocations += toolData.invocations || 0;
+      totalSuccesses += toolData.successes || 0;
+    }
+  }
+
+  if (totalInvocations === 0) {
+    return { value: null, sampleSize: 0 };
+  }
+
+  return {
+    value: totalSuccesses / totalInvocations,
+    sampleSize: totalInvocations,
+  };
+}
+
+/**
+ * Calculate percentage change between baseline and test.
+ * For success rates: positive = improvement
+ * For duration: negative = improvement (faster)
+ * @param {number} baseline
+ * @param {number} test
+ * @param {string} metric
+ * @returns {number} Change as decimal (-0.15 = 15% worse, 0.15 = 15% better)
+ */
+function calculateChange(baseline, test, metric) {
+  if (baseline === 0 || baseline == null || test == null) {
+    return null;
+  }
+
+  const rawChange = (test - baseline) / baseline;
+
+  // For duration, lower is better, so invert
+  if (metric === 'duration_min') {
+    return -rawChange;
+  }
+
+  return rawChange;
+}
+
+/**
+ * Validate all hypotheses in playbooks.md against session metrics.
+ * Compares baseline (before hypothesis) vs test (after hypothesis) periods.
+ *
+ * Decision rules (from Phase 4 spec):
+ * - 3+ test sessions AND metric improved by >10% -> promote
+ * - 3+ test sessions AND metric worsened by >10% -> reject
+ * - Otherwise -> continue (need more data)
+ *
+ * @param {string} playbooksPath - Path to playbooks.md
+ * @param {string} summariesPath - Path to summaries.ndjson
+ * @returns {Array<{ hypothesis: string, decision: 'promote'|'reject'|'continue', evidence: string, metrics: object }>}
+ */
+function validateHypotheses(playbooksPath, summariesPath) {
+  const playbooks = parsePlaybooks(playbooksPath);
+  const summaries = loadSummaries(summariesPath);
+  const state = loadState();
+  const results = [];
+
+  // Filter for hypothesis/testing entries (status may contain extra text)
+  const hypotheses = playbooks.filter(p =>
+    p.status.includes('hypothesis') || p.status.includes('testing')
+  );
+
+  const currentSessionCount = summaries.length;
+
+  for (const hyp of hypotheses) {
+    // Initialize tracking if new hypothesis
+    if (!state.hypotheses[hyp.name]) {
+      state.hypotheses[hyp.name] = {
+        firstSeenAt: currentSessionCount,
+        sessionCountAtStart: currentSessionCount,
+      };
+    }
+
+    const tracking = state.hypotheses[hyp.name];
+    const target = extractMetricTarget(hyp.section);
+
+    // Split sessions into baseline (before hypothesis) and test (after)
+    const baselineSessions = summaries.slice(0, tracking.firstSeenAt);
+    const testSessions = summaries.slice(tracking.firstSeenAt);
+
+    const baselineMetric = computeMetric(baselineSessions, target);
+    const testMetric = computeMetric(testSessions, target);
+
+    const change = calculateChange(baselineMetric.value, testMetric.value, target.metric);
+
+    // Build evidence string
+    const evidenceParts = [];
+    evidenceParts.push(`Target: ${target.target} (${target.metric})`);
+    evidenceParts.push(`Baseline: ${baselineMetric.value?.toFixed(3) ?? 'N/A'} (${baselineMetric.sampleSize} samples)`);
+    evidenceParts.push(`Test: ${testMetric.value?.toFixed(3) ?? 'N/A'} (${testMetric.sampleSize} samples)`);
+    if (change != null) {
+      const changePercent = (change * 100).toFixed(1);
+      evidenceParts.push(`Change: ${change > 0 ? '+' : ''}${changePercent}%`);
+    }
+    evidenceParts.push(`Test sessions: ${testSessions.length}`);
+
+    // Decision logic
+    let decision = 'continue';
+    let reason = '';
+
+    if (testSessions.length < MIN_TEST_SESSIONS) {
+      reason = `Need ${MIN_TEST_SESSIONS}+ test sessions, have ${testSessions.length}`;
+    } else if (change == null) {
+      reason = 'Insufficient metric data for comparison';
+    } else if (change >= IMPROVEMENT_THRESHOLD) {
+      decision = 'promote';
+      reason = `Improved by ${(change * 100).toFixed(1)}% (>${IMPROVEMENT_THRESHOLD * 100}% threshold)`;
+    } else if (change <= -IMPROVEMENT_THRESHOLD) {
+      decision = 'reject';
+      reason = `Worsened by ${(-change * 100).toFixed(1)}% (>${IMPROVEMENT_THRESHOLD * 100}% threshold)`;
+    } else {
+      reason = `Change of ${(change * 100).toFixed(1)}% within neutral zone (±${IMPROVEMENT_THRESHOLD * 100}%)`;
+    }
+
+    results.push({
+      hypothesis: hyp.name,
+      status: hyp.status,
+      decision,
+      evidence: evidenceParts.join(' | ') + ` | ${reason}`,
+      metrics: {
+        target,
+        baseline: baselineMetric,
+        test: testMetric,
+        change,
+        testSessionCount: testSessions.length,
+      },
+    });
+  }
+
+  // Save updated state
+  saveState(state);
+
+  return results;
+}
+
+/**
+ * Get a summary of hypothesis validation status.
+ * @param {Array} results - Output from validateHypotheses
+ * @returns {object} { total, promote, reject, continue, summary: string }
+ */
+function summarizeResults(results) {
+  const counts = {
+    total: results.length,
+    promote: results.filter(r => r.decision === 'promote').length,
+    reject: results.filter(r => r.decision === 'reject').length,
+    continue: results.filter(r => r.decision === 'continue').length,
+  };
+
+  const lines = [
+    `Hypothesis validation: ${counts.total} total`,
+    `  Promote: ${counts.promote}`,
+    `  Reject: ${counts.reject}`,
+    `  Continue: ${counts.continue}`,
+  ];
+
+  for (const r of results) {
+    lines.push(`  - [${r.decision.toUpperCase()}] ${r.hypothesis}`);
+  }
+
+  return { ...counts, summary: lines.join('\n') };
+}
+
+// CLI mode
+if (require.main === module) {
+  const playbooksPath = process.argv[2] || path.join(__dirname, '..', 'orchestrator', 'playbooks.md');
+  const summariesPath = process.argv[3] || SUMMARIES_PATH;
+
+  console.log('Validating hypotheses...');
+  console.log('  Playbooks:', playbooksPath);
+  console.log('  Summaries:', summariesPath);
+  console.log('');
+
+  const results = validateHypotheses(playbooksPath, summariesPath);
+  const summary = summarizeResults(results);
+
+  console.log(summary.summary);
+  console.log('');
+  console.log('Details:');
+  for (const r of results) {
+    console.log(`\n${r.hypothesis}:`);
+    console.log(`  Decision: ${r.decision}`);
+    console.log(`  Evidence: ${r.evidence}`);
+  }
+}
+
+module.exports = {
+  validateHypotheses,
+  summarizeResults,
+  extractMetricTarget,
+  loadSummaries,
+  computeMetric,
+  calculateChange,
+  STATE_PATH,
+};