ninja-terminals 2.0.0

package/lib/scheduler.js

@@ -0,0 +1,212 @@
+'use strict';
+
+/**
+ * Maximum "rest" duration (ms) for recency scoring.
+ * Terminals resting longer than this get max recency score.
+ */
+const MAX_REST_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Context usage threshold. Terminals above this are excluded.
+ */
+const CONTEXT_THRESHOLD = 80;
+
+/**
+ * Scoring weights (must sum to 1.0).
+ */
+const WEIGHT_AFFINITY = 0.4;
+const WEIGHT_CAPACITY = 0.4;
+const WEIGHT_RECENCY = 0.2;
+
+/**
+ * Check whether two scope arrays have overlapping paths.
+ * A path overlaps if one is a prefix of the other (directory containment)
+ * or if they are identical.
+ *
+ * @param {string[]} scopeA
+ * @param {string[]} scopeB
+ * @returns {boolean}
+ */
+function scopesOverlap(scopeA, scopeB) {
+  for (const a of scopeA) {
+    for (const b of scopeB) {
+      if (a === b || a.startsWith(b) || b.startsWith(a)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Compute affinity score: how many of the task's scope paths overlap with
+ * the terminal's previousFiles. Returns 0-100.
+ *
+ * @param {string[]} taskScope - File/directory paths the task owns
+ * @param {string[]} previousFiles - Files the terminal has worked on
+ * @returns {number} 0-100
+ */
+function computeAffinity(taskScope, previousFiles) {
+  if (!taskScope || taskScope.length === 0) return 50; // neutral if no scope
+  if (!previousFiles || previousFiles.length === 0) return 0;
+
+  let matches = 0;
+  for (const scopePath of taskScope) {
+    for (const file of previousFiles) {
+      if (file === scopePath || file.startsWith(scopePath) || scopePath.startsWith(file)) {
+        matches++;
+        break; // count each scope path at most once
+      }
+    }
+  }
+
+  return Math.round((matches / taskScope.length) * 100);
+}
+
+/**
+ * Compute capacity score from context percentage. More headroom = higher score.
+ *
+ * @param {number} contextPct - Current context window usage (0-100)
+ * @returns {number} 0-100
+ */
+function computeCapacity(contextPct) {
+  return Math.max(0, Math.min(100, 100 - contextPct));
+}
+
+/**
+ * Compute recency score: how long the terminal has been resting.
+ * Longer rest = higher score, capped at MAX_REST_MS.
+ *
+ * @param {number|null} lastTaskCompletedAt - Timestamp of last task completion
+ * @returns {number} 0-100
+ */
+function computeRecency(lastTaskCompletedAt) {
+  if (!lastTaskCompletedAt) return 100; // never used = fully rested
+  const elapsed = Date.now() - lastTaskCompletedAt;
+  if (elapsed <= 0) return 0;
+  return Math.round(Math.min(elapsed / MAX_REST_MS, 1) * 100);
+}
+
+/**
+ * Filter terminals that cannot accept a given task.
+ *
+ * Exclusion criteria:
+ * - Status is not 'idle'
+ * - contextPct exceeds threshold (>80)
+ * - Circuit breaker is OPEN
+ * - Scope conflicts with task scope
+ *
+ * @param {object[]} terminals - Array of terminal status objects
+ * @param {object} task - Task object with scope property
+ * @returns {object[]} Filtered array of eligible terminals
+ * @throws {Error} If inputs are invalid
+ */
+function filterTerminals(terminals, task) {
+  if (!Array.isArray(terminals)) {
+    throw new Error('terminals must be an array');
+  }
+  if (!task || typeof task !== 'object') {
+    throw new Error('task must be a non-null object');
+  }
+
+  const taskScope = Array.isArray(task.scope) ? task.scope : [];
+
+  return terminals.filter((terminal) => {
+    // Must be idle
+    if (terminal.status !== 'idle') return false;
+
+    // Must have context headroom
+    if (typeof terminal.contextPct === 'number' && terminal.contextPct > CONTEXT_THRESHOLD) {
+      return false;
+    }
+
+    // Circuit breaker must not be open
+    if (terminal.circuitBreakerState === 'OPEN') return false;
+
+    // Scope must not conflict (only if both have scope)
+    if (
+      taskScope.length > 0 &&
+      Array.isArray(terminal.scope) &&
+      terminal.scope.length > 0 &&
+      scopesOverlap(taskScope, terminal.scope)
+    ) {
+      return false;
+    }
+
+    return true;
+  });
+}
+
+/**
+ * Score eligible terminal candidates for a task using a weighted multi-factor model.
+ *
+ * Factors and weights:
+ * - Affinity  (40%): overlap between task scope and terminal's previous files
+ * - Capacity  (40%): available context window headroom
+ * - Recency   (20%): time since last task completion (longer rest = better)
+ *
+ * @param {object[]} candidates - Filtered array of terminal status objects
+ * @param {object} task - Task object with scope property
+ * @returns {object[]} Candidates with `.score` property, sorted descending by score
+ * @throws {Error} If inputs are invalid
+ */
+function scoreTerminals(candidates, task) {
+  if (!Array.isArray(candidates)) {
+    throw new Error('candidates must be an array');
+  }
+  if (!task || typeof task !== 'object') {
+    throw new Error('task must be a non-null object');
+  }
+
+  const taskScope = Array.isArray(task.scope) ? task.scope : [];
+
+  const scored = candidates.map((terminal) => {
+    const affinity = computeAffinity(
+      taskScope,
+      Array.isArray(terminal.previousFiles) ? terminal.previousFiles : []
+    );
+    const capacity = computeCapacity(
+      typeof terminal.contextPct === 'number' ? terminal.contextPct : 0
+    );
+    const recency = computeRecency(terminal.lastTaskCompletedAt || null);
+
+    const score = Math.round(
+      affinity * WEIGHT_AFFINITY +
+        capacity * WEIGHT_CAPACITY +
+        recency * WEIGHT_RECENCY
+    );
+
+    return { ...terminal, score };
+  });
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored;
+}
+
+/**
+ * Convenience function: filter, score, and select the best terminal for a task.
+ *
+ * @param {object[]} terminals - Array of terminal status objects
+ * @param {object} task - Task object
+ * @returns {object|null} Best terminal with score, or null if none eligible
+ */
+function selectTerminal(terminals, task) {
+  if (!Array.isArray(terminals)) {
+    throw new Error('terminals must be an array');
+  }
+  if (!task || typeof task !== 'object') {
+    throw new Error('task must be a non-null object');
+  }
+
+  const filtered = filterTerminals(terminals, task);
+  if (filtered.length === 0) return null;
+
+  const scored = scoreTerminals(filtered, task);
+  return scored.length > 0 ? scored[0] : null;
+}
+
+module.exports = {
+  filterTerminals,
+  scoreTerminals,
+  selectTerminal,
+};

package/lib/settings-gen.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Worker settings generator
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a Claude Code worker settings object for a terminal.
+ *
+ * @param {number|string} terminalId - Terminal identifier
+ * @param {string|string[]} scope    - File scope path(s), or '*'/'' for unrestricted
+ * @param {Object}          [options={}]
+ * @param {number}          [options.port=3000]          - Server port for hook URLs
+ * @param {string[]}        [options.additionalAllow=[]] - Extra allow rules to merge
+ * @param {string[]}        [options.additionalDeny=[]]  - Extra deny rules to merge
+ * @returns {Object} Settings object suitable for `.claude/settings.local.json`
+ */
+function generateWorkerSettings(terminalId, scope, options = {}) {
+  const port = options.port || 3000;
+  const additionalAllow = options.additionalAllow || [];
+  const additionalDeny = options.additionalDeny || [];
+
+  // Build Edit/Write rules based on scope
+  const editWriteRules = [];
+  const unrestricted = !scope || scope === '*' || (Array.isArray(scope) && scope.length === 0);
+
+  if (unrestricted) {
+    editWriteRules.push('Edit', 'Write');
+  } else {
+    const scopes = Array.isArray(scope) ? scope : [scope];
+    for (const s of scopes) {
+      // Normalize: ensure trailing /** for glob matching
+      const normalized = s.endsWith('/**') ? s : (s.endsWith('/') ? `${s}**` : `${s}/**`);
+      const scopePath = normalized.startsWith('/') ? normalized : `/${normalized}`;
+      editWriteRules.push(`Edit(${scopePath})`, `Write(${scopePath})`);
+    }
+  }
+
+  const allow = [
+    'Read',
+    'Glob',
+    'Grep',
+    ...editWriteRules,
+    // Safe bash commands
+    'Bash(npm test *)',
+    'Bash(npm run *)',
+    'Bash(node *)',
+    'Bash(npx *)',
+    'Bash(git diff *)',
+    'Bash(git log *)',
+    'Bash(git status)',
+    'Bash(ls *)',
+    'Bash(cat *)',
+    'Bash(wc *)',
+    'Bash(head *)',
+    'Bash(tail *)',
+    'Bash(mkdir *)',
+    'Bash(cp *)',
+    // MCP tools — all enabled servers
+    'mcp__studychat__*',
+    'mcp__postforme__*',
+    'mcp__render-billing__*',
+    'mcp__netlify-billing__*',
+    'mcp__chrome-devtools__*',
+    'mcp__gkchatty-production__*',
+    'mcp__builder-pro-mcp__*',
+    'mcp__gmail__*',
+    'mcp__c2c__*',
+    'mcp__atlas-architect__*',
+    // Network and research
+    'WebFetch(*)',
+    'WebSearch(*)',
+    // Additional bash
+    'Bash(curl *)',
+    'Bash(cd *)',
+    'Bash(grep *)',
+    'Bash(find *)',
+    'Bash(echo *)',
+    'Bash(sleep *)',
+    'Bash(kill *)',
+    'Bash(lsof *)',
+    'Bash(ps *)',
+    'Bash(git add *)',
+    'Bash(git commit *)',
+    'Bash(git push *)',
+    // Sub-agents
+    'Agent(*)',
+    ...additionalAllow,
+  ];
+
+  const deny = [
+    'Bash(rm -rf *)',
+    'Bash(git push --force *)',
+    'Bash(sudo *)',
+    'Bash(chmod *)',
+    'Bash(chown *)',
+    'Read(./.env)',
+    'Read(./.env.*)',
+    'Read(~/.ssh/**)',
+    'Read(~/.aws/**)',
+    'Edit(./.env)',
+    'Edit(./.env.*)',
+    ...additionalDeny,
+  ];
+
+  return {
+    permissions: { allow, deny },
+    sandbox: {
+      enabled: false,
+    },
+  };
+}
+
+/**
+ * Generate and write worker settings to disk.
+ *
+ * @param {number|string} terminalId - Terminal identifier
+ * @param {string}        projectDir - Absolute path to the project directory
+ * @param {string|string[]} scope    - File scope path(s)
+ * @param {Object}        [options={}]
+ * @returns {string} Absolute path to the written settings file
+ */
+function writeWorkerSettings(terminalId, projectDir, scope, options = {}) {
+  const settings = generateWorkerSettings(terminalId, scope, options);
+  const claudeDir = path.join(projectDir, '.claude');
+  const settingsPath = path.join(claudeDir, 'settings.local.json');
+
+  // Create .claude/ directory if it doesn't exist
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+
+  // Merge with existing settings instead of overwriting
+  let existing = {};
+  try {
+    if (fs.existsSync(settingsPath)) {
+      existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    }
+  } catch { /* ignore parse errors, start fresh */ }
+
+  // Merge permissions: deduplicate allow/deny lists
+  const mergedAllow = [...new Set([...(existing.permissions?.allow || []), ...settings.permissions.allow])];
+  const mergedDeny = [...new Set([...(existing.permissions?.deny || []), ...settings.permissions.deny])];
+
+  const merged = {
+    ...existing,
+    permissions: { allow: mergedAllow, deny: mergedDeny },
+    sandbox: settings.sandbox,
+    // Preserve existing hooks, enabledMcpjsonServers, etc.
+  };
+
+  fs.writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  return settingsPath;
+}
+
+module.exports = { generateWorkerSettings, writeWorkerSettings };

package/lib/sse.js

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * Server-Sent Events manager.
+ * Maintains a set of connected Express response objects and broadcasts
+ * named events to all of them.
+ */
+class SSEManager {
+  constructor() {
+    /** @type {Set<import('http').ServerResponse>} */
+    this._clients = new Set();
+    /** @type {NodeJS.Timeout|null} */
+    this._heartbeatTimer = null;
+  }
+
+  /**
+   * Register an Express response as an SSE client.
+   * Sets the required headers, sends an initial keepalive comment,
+   * and automatically removes the client on connection close.
+   *
+   * @param {import('http').ServerResponse} res - Express response object
+   */
+  addClient(res) {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no', // disable nginx buffering if proxied
+    });
+    res.write(':ok\n\n');
+
+    this._clients.add(res);
+
+    res.on('close', () => {
+      this._clients.delete(res);
+    });
+  }
+
+  /**
+   * Explicitly remove an SSE client.
+   * @param {import('http').ServerResponse} res
+   */
+  removeClient(res) {
+    this._clients.delete(res);
+  }
+
+  /**
+   * Broadcast a named event with JSON data to every connected client.
+   * Silently drops clients whose connections have ended.
+   *
+   * @param {string} eventName - SSE event name
+   * @param {*}      data      - Payload (will be JSON-stringified)
+   */
+  broadcast(eventName, data) {
+    const frame = `event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const client of this._clients) {
+      if (client.writableEnded) {
+        this._clients.delete(client);
+        continue;
+      }
+      client.write(frame);
+    }
+  }
+
+  /**
+   * Start sending periodic heartbeat comments to keep connections alive.
+   * @param {number} [intervalMs=15000] - Heartbeat interval in milliseconds
+   */
+  startHeartbeat(intervalMs = 15000) {
+    this.stopHeartbeat();
+    this._heartbeatTimer = setInterval(() => {
+      for (const client of this._clients) {
+        if (client.writableEnded) {
+          this._clients.delete(client);
+          continue;
+        }
+        client.write(': heartbeat\n\n');
+      }
+    }, intervalMs);
+    // Allow the process to exit even if the timer is running
+    if (this._heartbeatTimer.unref) {
+      this._heartbeatTimer.unref();
+    }
+  }
+
+  /** Stop the heartbeat timer. */
+  stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
+  /**
+   * Number of currently connected SSE clients.
+   * @returns {number}
+   */
+  get clientCount() {
+    return this._clients.size;
+  }
+}
+
+module.exports = { SSEManager };

package/lib/status-detect.js

@@ -0,0 +1,229 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// ANSI stripping
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip all ANSI escape sequences and carriage returns from a string.
+ * @param {string} str
+ * @returns {string}
+ */
+function stripAnsi(str) {
+  return str
+    .replace(/\x1b\][^\x07]*\x07/g, '')          // OSC sequences
+    .replace(/\x1b\[[?>=!]?[0-9;]*[a-zA-Z]/g, '') // CSI sequences
+    .replace(/\x1b[()][0-9A-Z]/g, '')             // character set selection
+    .replace(/\x1b[>=<]/g, '')                     // keypad mode
+    .replace(/\x1b\[>[0-9;]*[a-zA-Z]/g, '')       // private CSI
+    .replace(/\r/g, '')
+    .trim();
+}
+
+// ---------------------------------------------------------------------------
+// Status detection
+// ---------------------------------------------------------------------------
+
+/** Regex that matches status-bar noise lines that should be excluded. */
+const STATUS_BAR_NOISE = /^(●|·|\/effort|\/mcp|high|low|medium|Failed to install|MCP server|Will retry|─+$|\?forshortcuts|forshortcuts)/i;
+
+/** Regex that matches tool invocation patterns. */
+const TOOL_RE = /Bash\(|Read\(|Edit\(|Write\(|Grep\(|Glob\(|Agent\(/i;
+
+/** Spinner / thinking indicators. */
+const SPINNER_RE = /[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]|Thinking|Generating/i;
+
+/**
+ * Detect the current operational status of a Claude Code terminal.
+ *
+ * @param {string[]} lines - Array of ANSI-stripped lines (from LineBuffer)
+ * @returns {'idle'|'working'|'waiting_approval'|'compacting'|'done'|'blocked'|'error'}
+ */
+function detectStatus(lines) {
+  if (!lines || lines.length === 0) return 'idle';
+
+  // Work with trimmed, non-empty lines
+  const trimmed = lines.map(l => l.trim()).filter(Boolean);
+  if (trimmed.length === 0) return 'idle';
+
+  const last50 = trimmed.slice(-50).join('\n');
+  const contentLines = trimmed.filter(l => !STATUS_BAR_NOISE.test(l));
+  const lastContentLine = contentLines.slice(-1)[0] || '';
+  const last10 = trimmed.slice(-10);
+
+  // Prompt detection — idle if prompt is visible and no recent tool work
+  const hasPrompt = last10.some(l => /^[>❯]$/.test(l));
+  const hasShortcutsHint = last10.some(
+    l => /\?.*for\s*shortcuts/i.test(l) || l === '?forshortcuts'
+  );
+
+  if (hasPrompt || hasShortcutsHint) {
+    const recentWork = last10.some(l => TOOL_RE.test(l));
+    if (!recentWork) return 'idle';
+  }
+
+  // Approval prompts
+  if (/Select any you wish to enable|Space to select|Enter to confirm/i.test(last50)) {
+    return 'waiting_approval';
+  }
+  if (/accept edits|allow bash|Yes\/No|\(y\/n\)/i.test(last50)) {
+    return 'waiting_approval';
+  }
+
+  // Auto-compaction
+  if (/auto-compact|compressing|compacting/i.test(last50)) return 'compacting';
+
+  // Explicit status markers (convention for orchestrator scripts)
+  if (/STATUS: DONE/i.test(last50)) return 'done';
+  if (/STATUS: BLOCKED/i.test(last50)) return 'blocked';
+
+  // Active tool use
+  if (TOOL_RE.test(last50)) return 'working';
+
+  // Spinner / thinking
+  if (SPINNER_RE.test(lastContentLine)) return 'working';
+
+  // Error detection in very recent output
+  const last3 = contentLines.slice(-3).join('\n');
+  if (/panic:|Traceback \(most recent/i.test(last3)) return 'error';
+
+  // Default to working (Claude is likely generating)
+  return 'working';
+}
+
+// ---------------------------------------------------------------------------
+// Context window percentage extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract context-window usage percentage from terminal output.
+ * Looks for patterns like "Context: 42%" or "context window: 72%".
+ *
+ * @param {string[]} lines - Array of ANSI-stripped lines
+ * @returns {number|null} Percentage (0-100) or null if not found
+ */
+function extractContextPct(lines) {
+  if (!lines || lines.length === 0) return null;
+
+  // Scan from the end — most recent value wins
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const match = lines[i].match(/context(?:\s*window)?[:\s]+(\d{1,3})%/i);
+    if (match) {
+      const pct = parseInt(match[1], 10);
+      if (pct >= 0 && pct <= 100) return pct;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Structured event extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} StructuredEvent
+ * @property {string} ts        - ISO 8601 timestamp
+ * @property {string} type      - Event type: status | progress | tool | build | error | need | contract | context
+ * @property {string} terminal  - Terminal label (e.g. "T1")
+ * @property {string} msg       - Raw message content
+ * @property {Object} [meta]    - Type-specific metadata
+ */
+
+/**
+ * Line prefix patterns for structured events.
+ * Convention: lines prefixed with `STATUS:`, `PROGRESS:`, `NEED:`, etc.
+ * are treated as structured events emitted by orchestrated Claude sessions.
+ */
+const EVENT_PATTERNS = [
+  { re: /^STATUS:\s*(.+)/i,    type: 'status' },
+  { re: /^PROGRESS:\s*(.+)/i,  type: 'progress' },
+  { re: /^NEED:\s*(.+)/i,      type: 'need' },
+  { re: /^CONTRACT:\s*(.+)/i,  type: 'contract' },
+  { re: /^BUILD:\s*(.+)/i,     type: 'build' },
+  { re: /^INSIGHT:\s*(.+)/i,   type: 'insight' },
+  { re: /^PLAYBOOK:\s*(.+)/i,  type: 'playbook' },
+  { re: /^ERROR_RESOLVED:\s*(.+)/i, type: 'error_resolved' },
+];
+
+/** Tool invocation pattern for extracting tool events. */
+const TOOL_INVOKE_RE = /^(Bash|Read|Edit|Write|Grep|Glob|Agent)\((.+)\)/;
+
+/** Error pattern. */
+const ERROR_RE = /^(Error|panic:|Traceback \(most recent|FATAL|ENOENT|EACCES)/i;
+
+/** Context window pattern. */
+const CONTEXT_RE = /context(?:\s*window)?[:\s]+(\d{1,3})%/i;
+
+/**
+ * Parse an array of stripped lines into structured JSONL-compatible event objects.
+ *
+ * @param {string[]} lines          - ANSI-stripped lines to parse
+ * @param {string}   terminalLabel  - Label for the terminal (e.g. "T1")
+ * @returns {StructuredEvent[]}
+ */
+function extractStructuredEvents(lines, terminalLabel) {
+  if (!lines || lines.length === 0) return [];
+
+  const events = [];
+  const ts = new Date().toISOString();
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Check structured prefixes first
+    let matched = false;
+    for (const { re, type } of EVENT_PATTERNS) {
+      const m = trimmed.match(re);
+      if (m) {
+        events.push({ ts, type, terminal: terminalLabel, msg: m[1].trim() });
+        matched = true;
+        break;
+      }
+    }
+    if (matched) continue;
+
+    // Tool invocations
+    const toolMatch = trimmed.match(TOOL_INVOKE_RE);
+    if (toolMatch) {
+      events.push({
+        ts,
+        type: 'tool',
+        terminal: terminalLabel,
+        msg: trimmed,
+        meta: { tool: toolMatch[1], args: toolMatch[2] },
+      });
+      continue;
+    }
+
+    // Errors
+    if (ERROR_RE.test(trimmed)) {
+      events.push({ ts, type: 'error', terminal: terminalLabel, msg: trimmed });
+      continue;
+    }
+
+    // Context window updates
+    const ctxMatch = trimmed.match(CONTEXT_RE);
+    if (ctxMatch) {
+      const pct = parseInt(ctxMatch[1], 10);
+      if (pct >= 0 && pct <= 100) {
+        events.push({
+          ts,
+          type: 'context',
+          terminal: terminalLabel,
+          msg: trimmed,
+          meta: { pct },
+        });
+      }
+    }
+  }
+
+  return events;
+}
+
+module.exports = {
+  stripAnsi,
+  detectStatus,
+  extractContextPct,
+  extractStructuredEvents,
+};