sentinelayer-cli 0.1.0

package/src/agents/jules/stream.js

@@ -0,0 +1,186 @@
+import { PERSONA_VISUALS, resolvePersonaVisual } from "./config/definition.js";
+
+/**
+ * Jules Tanaka — Streaming Event Formatter
+ *
+ * Formats NDJSON events for external agent consumption and terminal display.
+ * Universal envelope: every event carries agent identity, usage snapshot, timestamp.
+ */
+
+const SCHEMA_VERSION = 1;
+
+/**
+ * Build an NDJSON event envelope.
+ *
+ * @param {string} event - Event type (agent_start, tool_call, finding, heartbeat, etc.)
+ * @param {object} agentIdentity - { id, persona, color?, avatar? }
+ * @param {object} payload - Event-specific data
+ * @param {object} [usage] - Running usage totals
+ * @param {string} [runId] - Run identifier
+ * @returns {object} Complete event envelope
+ */
+export function buildStreamEvent(event, agentIdentity, payload, usage, runId) {
+  const visual = resolvePersonaVisual(agentIdentity?.id) || {};
+  return {
+    stream: "sl_event",
+    version: SCHEMA_VERSION,
+    command: "audit.deep",
+    runId: runId || null,
+    timestamp: new Date().toISOString(),
+    agent: {
+      id: agentIdentity?.id || "unknown",
+      persona: agentIdentity?.persona || visual.fullName || "unknown",
+      color: agentIdentity?.color || visual.color || "white",
+      avatar: agentIdentity?.avatar || visual.avatar || "",
+    },
+    event,
+    payload: payload || {},
+    usage: usage || {},
+  };
+}
+
+/**
+ * Create a streaming emitter bound to a specific agent and run.
+ *
+ * @param {object} config
+ * @param {object} config.agentIdentity - { id, persona }
+ * @param {string} config.runId
+ * @param {function} [config.onEvent] - Callback for each event
+ * @param {boolean} [config.stdoutNdjson] - Also write to stdout as NDJSON
+ * @returns {{ emit(event, payload, usage), close() }}
+ */
+export function createStreamEmitter({ agentIdentity, runId, onEvent, stdoutNdjson = false }) {
+  let closed = false;
+  const usageRef = { costUsd: 0, outputTokens: 0, toolCalls: 0, durationMs: 0 };
+
+  return {
+    /**
+     * Emit a streaming event.
+     */
+    emit(event, payload, usage) {
+      if (closed) return;
+      const merged = { ...usageRef, ...usage };
+      Object.assign(usageRef, merged);
+      const evt = buildStreamEvent(event, agentIdentity, payload, merged, runId);
+      if (onEvent) onEvent(evt);
+      if (stdoutNdjson) console.log(JSON.stringify(evt));
+      return evt;
+    },
+
+    /**
+     * Update accumulated usage without emitting.
+     */
+    updateUsage(delta) {
+      if (delta.costUsd !== undefined) usageRef.costUsd = delta.costUsd;
+      if (delta.outputTokens !== undefined) usageRef.outputTokens = delta.outputTokens;
+      if (delta.toolCalls !== undefined) usageRef.toolCalls = delta.toolCalls;
+      if (delta.durationMs !== undefined) usageRef.durationMs = delta.durationMs;
+    },
+
+    /**
+     * Mark emitter as closed (no more events).
+     */
+    close() {
+      closed = true;
+    },
+
+    /**
+     * Get current usage snapshot.
+     */
+    getUsage() {
+      return { ...usageRef };
+    },
+  };
+}
+
+/**
+ * Format a terminal display line for a persona event (non-JSON mode).
+ *
+ * @param {object} evt - Stream event
+ * @returns {string} Formatted line for stderr
+ */
+export function formatTerminalLine(evt) {
+  const agent = evt.agent || {};
+  const avatar = agent.avatar || "";
+  const name = agent.persona || agent.id || "Agent";
+  const p = evt.payload || {};
+
+  switch (evt.event) {
+    case "agent_start":
+      return `${avatar} ${name} starting (mode: ${p.mode || "primary"})...`;
+
+    case "progress":
+      return `${avatar} ${name}: ${p.message || p.phase || "working..."}`;
+
+    case "tool_call":
+      return `${avatar} ${name} [${p.tool}] ${formatToolInput(p.input)}`;
+
+    case "tool_result":
+      return `${avatar} ${name} [${p.tool}] ${p.durationMs || 0}ms ${p.success === false ? "FAILED" : "ok"}`;
+
+    case "finding": {
+      const sev = p.severity || "P3";
+      const sevColor = sev === "P0" ? "!!!" : sev === "P1" ? "!!" : sev === "P2" ? "!" : "";
+      return `${avatar} [${sev}${sevColor}] ${p.file || ""}:${p.line || ""} ${p.title || ""}`;
+    }
+
+    case "reasoning":
+      return `${avatar} ${name}: ${(p.summary || "").slice(0, 120)}`;
+
+    case "heartbeat": {
+      const h = p;
+      const budgetPct = h.budgetRemaining?.pct?.toFixed(0) || "?";
+      return `${avatar} ${name} [${h.turnsCompleted || 0}/${h.turnsMax || "?"} turns, ${budgetPct}% budget, ${h.findingsSoFar || 0} findings]`;
+    }
+
+    case "budget_warning":
+      return `${avatar} ${name} BUDGET WARNING: ${(p.warnings || []).map(w => w.code).join(", ")}`;
+
+    case "budget_stop":
+      return `${avatar} ${name} BUDGET STOP: ${(p.reasons || []).map(r => r.code || r).join(", ")}`;
+
+    case "swarm_start":
+      return `${avatar} ${name} spawning sub-agents (${p.scannerCount || 0} scanners, ${p.hunterCount || 0} hunters)...`;
+
+    case "swarm_complete":
+      return `${avatar} ${name} swarm complete: ${p.totalFindings || 0} findings from ${p.totalAgents || 0} agents ($${(p.totalCostUsd || 0).toFixed(2)})`;
+
+    case "phase_start":
+      return `${avatar} ${name} phase: ${p.phase || "unknown"}`;
+
+    case "agent_complete": {
+      const s = p;
+      return `${avatar} ${name} complete: ${s.total || 0} findings (P0=${s.P0 || 0} P1=${s.P1 || 0} P2=${s.P2 || 0}) $${(s.costUsd || 0).toFixed(2)} ${s.durationMs ? (s.durationMs / 1000).toFixed(1) + "s" : ""}`;
+    }
+
+    case "agent_abort":
+      return `${avatar} ${name} ABORTED: ${p.reason || "unknown"}`;
+
+    default:
+      return `${avatar} ${name} [${evt.event}]`;
+  }
+}
+
+function formatToolInput(input) {
+  if (!input) return "";
+  if (input.file_path) return input.file_path;
+  if (input.pattern) return `/${input.pattern}/`;
+  if (input.operation) return input.operation;
+  if (input.command) return input.command.slice(0, 60);
+  return "";
+}
+
+/**
+ * List all valid event types.
+ */
+export const EVENT_TYPES = Object.freeze([
+  "agent_start", "agent_complete", "agent_abort", "agent_error",
+  "progress", "heartbeat",
+  "tool_call", "tool_result",
+  "finding", "reasoning",
+  "budget_warning", "budget_stop",
+  "swarm_start", "swarm_complete",
+  "phase_start", "phase_complete",
+  "convergence_expansion", "coverage_gap",
+  "llm_error",
+]);

package/src/agents/jules/swarm/file-scanner.js

@@ -0,0 +1,74 @@
+import { JulesSubAgent } from "./sub-agent.js";
+
+const FILE_SCANNER_PROMPT = `You are a FileScanner sub-agent working for Jules Tanaka (SentinelLayer Frontend Specialist).
+
+Your job: Read each file in your scope and extract a structured summary.
+
+For each file, extract:
+- componentName: the primary exported component/function name
+- useStateCount: number of useState calls
+- useEffectCount: number of useEffect calls
+- imports: list of imported modules (just the module names)
+- exports: list of exported names
+- loc: approximate line count
+- riskSignals: array of any of these detected patterns:
+  - "dangerouslySetInnerHTML" if found
+  - "eval" if found
+  - "window_access_in_render" if window/document/localStorage used outside useEffect
+  - "missing_cleanup" if useEffect has subscription/timer without return
+  - "god_component" if useState count >= 16
+  - "large_file" if LOC > 500
+
+Use the FileRead tool to read each file. Use Grep if you need to search for patterns.
+
+Return your findings as a JSON array in a \`\`\`json code block:
+[
+  {
+    "file": "path/to/file.tsx",
+    "componentName": "Dashboard",
+    "useStateCount": 3,
+    "useEffectCount": 2,
+    "imports": ["react", "zustand", "./Header"],
+    "exports": ["Dashboard"],
+    "loc": 150,
+    "riskSignals": [],
+    "discoveredDependencies": ["./utils/formatDate", "../hooks/useAuth"]
+  }
+]
+
+The discoveredDependencies field is critical: list any imports that point to files NOT in your assigned scope. These will be used to expand the audit coverage.
+
+Be thorough but concise. Do not explain findings — just extract data.`;
+
+/**
+ * Create a FileScanner sub-agent for a batch of files.
+ *
+ * @param {object} config
+ * @param {string} config.id - Unique ID (e.g., "scanner-dashboard")
+ * @param {string[]} config.files - Files to scan
+ * @param {object} config.budget - Budget slice
+ * @param {object} config.blackboard - Shared blackboard
+ * @param {object} [config.provider] - LLM provider overrides
+ * @param {AbortController} [config.parentAbort]
+ * @param {function} [config.onEvent]
+ */
+export function createFileScanner(config) {
+  return new JulesSubAgent({
+    id: config.id || `scanner-${Date.now()}`,
+    role: "FileScanner",
+    systemPrompt: FILE_SCANNER_PROMPT,
+    allowedTools: ["FileRead", "Grep", "Glob"],
+    scope: { files: config.files },
+    budget: config.budget || {
+      maxCostUsd: 0.5,
+      maxOutputTokens: 3000,
+      maxRuntimeMs: 60000,
+      maxToolCalls: config.files.length * 2 + 5,
+    },
+    blackboard: config.blackboard,
+    maxTurns: Math.min(config.files.length + 3, 15),
+    provider: config.provider,
+    parentAbort: config.parentAbort,
+    onEvent: config.onEvent,
+  });
+}

package/src/agents/jules/swarm/index.js

@@ -0,0 +1,11 @@
+/**
+ * Jules Tanaka — Sub-Agent Swarm
+ *
+ * Parallel isolated agents for frontend audit work.
+ * Each sub-agent: own conversation, own budget, shared blackboard.
+ */
+
+export { JulesSubAgent, runSubAgentBatch, SubAgentError } from "./sub-agent.js";
+export { createFileScanner } from "./file-scanner.js";
+export { createPatternHunter, HUNT_TYPES } from "./pattern-hunter.js";
+export { shouldSpawnSubAgents, runJulesSwarm } from "./orchestrator.js";

package/src/agents/jules/swarm/orchestrator.js

@@ -0,0 +1,362 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import fsp from "node:fs/promises";
+
+import { createFileScanner } from "./file-scanner.js";
+import { createPatternHunter, HUNT_TYPES } from "./pattern-hunter.js";
+import { runSubAgentBatch } from "./sub-agent.js";
+import { frontendAnalyze } from "../tools/frontend-analyze.js";
+import { createAgentContext } from "../tools/dispatch.js";
+
+/**
+ * Jules Swarm Orchestrator
+ *
+ * Coordinates parallel sub-agents for thorough frontend audit.
+ * Multi-pass convergence ensures no file is missed:
+ *   Pass 1 (FileScanners): Read all files, discover import deps
+ *   Pass 2 (PatternHunters): Search for 6 issue classes in parallel
+ *   Convergence: Expand scope with discovered deps, re-scan if needed
+ *   Coverage verification: Ensure every reachable file was read
+ */
+
+const SPAWN_THRESHOLDS = {
+  minFilesForSwarm: 15,
+  minRouteGroupsForSwarm: 3,
+  minLocForSwarm: 5000,
+  maxFilesPerScanner: 12,
+  maxConcurrentAgents: 4,
+};
+
+/**
+ * Decide whether the frontend surface warrants sub-agent spawning.
+ */
+export function shouldSpawnSubAgents(scopeMap) {
+  const frontendFiles = (scopeMap.primary || []).filter(f => isFrontendFile(f.path || f));
+  const routeGroups = detectRouteGroups(frontendFiles);
+  const totalLoc = frontendFiles.reduce((sum, f) => sum + (f.loc || 80), 0);
+
+  return {
+    spawn: (
+      frontendFiles.length > SPAWN_THRESHOLDS.minFilesForSwarm ||
+      routeGroups.length >= SPAWN_THRESHOLDS.minRouteGroupsForSwarm ||
+      totalLoc > SPAWN_THRESHOLDS.minLocForSwarm
+    ),
+    fileCount: frontendFiles.length,
+    routeGroups: routeGroups.length,
+    estimatedLoc: totalLoc,
+    reason: frontendFiles.length > SPAWN_THRESHOLDS.minFilesForSwarm
+      ? `${frontendFiles.length} frontend files exceeds threshold (${SPAWN_THRESHOLDS.minFilesForSwarm})`
+      : routeGroups.length >= SPAWN_THRESHOLDS.minRouteGroupsForSwarm
+        ? `${routeGroups.length} route groups exceeds threshold (${SPAWN_THRESHOLDS.minRouteGroupsForSwarm})`
+        : totalLoc > SPAWN_THRESHOLDS.minLocForSwarm
+          ? `${totalLoc} LOC exceeds threshold (${SPAWN_THRESHOLDS.minLocForSwarm})`
+          : "below all thresholds",
+  };
+}
+
+/**
+ * Run the full swarm orchestration: scanners → hunters → convergence → coverage.
+ *
+ * @param {object} config
+ * @param {object} config.scopeMap - { primary, secondary, tertiary } file lists
+ * @param {string} config.rootPath - Codebase root
+ * @param {object} config.blackboard - Shared blackboard instance
+ * @param {object} config.budget - Total budget for all sub-agents
+ * @param {object} [config.provider] - LLM provider overrides
+ * @param {AbortController} [config.parentAbort]
+ * @param {function} [config.onEvent]
+ * @returns {Promise<SwarmResult>}
+ */
+export async function runJulesSwarm(config) {
+  const {
+    scopeMap, rootPath, blackboard, budget,
+    provider, parentAbort, onEvent,
+  } = config;
+
+  const runId = `swarm-jules-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const startedAt = Date.now();
+  const allResults = [];
+
+  emit(onEvent, "swarm_start", {
+    runId,
+    phases: ["file_scan", "pattern_hunt", "convergence", "coverage_verify"],
+  });
+
+  // ── Phase 1: File Scanners ──────────────────────────────────────
+
+  const primaryFiles = (scopeMap.primary || []).map(f => f.path || f);
+  const partitions = partitionFiles(primaryFiles, SPAWN_THRESHOLDS.maxFilesPerScanner);
+
+  emit(onEvent, "phase_start", {
+    phase: "file_scan",
+    scannerCount: partitions.length,
+    totalFiles: primaryFiles.length,
+  });
+
+  const scannerBudgetSlice = divideBudget(budget, partitions.length + HUNT_TYPES.length);
+
+  const scanners = partitions.map((files, i) =>
+    createFileScanner({
+      id: `scanner-${i}`,
+      files,
+      budget: scannerBudgetSlice,
+      blackboard,
+      provider,
+      parentAbort,
+      onEvent,
+    }),
+  );
+
+  const scanResults = await runSubAgentBatch(scanners, {
+    maxConcurrent: SPAWN_THRESHOLDS.maxConcurrentAgents,
+  });
+  allResults.push(...scanResults);
+
+  emit(onEvent, "phase_complete", {
+    phase: "file_scan",
+    agentsCompleted: scanResults.length,
+    findingsCount: scanResults.reduce((s, r) => s + r.findings.length, 0),
+  });
+
+  // ── Phase 2: Pattern Hunters ────────────────────────────────────
+
+  emit(onEvent, "phase_start", {
+    phase: "pattern_hunt",
+    hunterCount: HUNT_TYPES.length,
+    huntTypes: HUNT_TYPES,
+  });
+
+  const hunterBudgetSlice = divideBudget(budget, partitions.length + HUNT_TYPES.length);
+
+  const hunters = HUNT_TYPES.map(huntType =>
+    createPatternHunter({
+      huntType,
+      rootPath,
+      budget: hunterBudgetSlice,
+      blackboard,
+      provider,
+      parentAbort,
+      onEvent,
+    }),
+  );
+
+  const huntResults = await runSubAgentBatch(hunters, {
+    maxConcurrent: SPAWN_THRESHOLDS.maxConcurrentAgents,
+  });
+  allResults.push(...huntResults);
+
+  emit(onEvent, "phase_complete", {
+    phase: "pattern_hunt",
+    agentsCompleted: huntResults.length,
+    findingsCount: huntResults.reduce((s, r) => s + r.findings.length, 0),
+  });
+
+  // ── Convergence: Expand scope from discovered deps ──────────────
+
+  emit(onEvent, "phase_start", { phase: "convergence" });
+
+  const discoveredDeps = collectDiscoveredDeps(scanResults);
+  const alreadyScanned = new Set(primaryFiles);
+  const newFiles = discoveredDeps.filter(f => !alreadyScanned.has(f));
+
+  let convergenceResults = [];
+  if (newFiles.length > 0 && newFiles.length <= 30) {
+    emit(onEvent, "convergence_expansion", {
+      newFilesDiscovered: newFiles.length,
+      spawningExtraScanner: true,
+    });
+
+    const extraPartitions = partitionFiles(newFiles, SPAWN_THRESHOLDS.maxFilesPerScanner);
+    const extraScanners = extraPartitions.map((files, i) =>
+      createFileScanner({
+        id: `scanner-convergence-${i}`,
+        files,
+        budget: scannerBudgetSlice,
+        blackboard,
+        provider,
+        parentAbort,
+        onEvent,
+      }),
+    );
+
+    convergenceResults = await runSubAgentBatch(extraScanners, {
+      maxConcurrent: SPAWN_THRESHOLDS.maxConcurrentAgents,
+    });
+    allResults.push(...convergenceResults);
+  }
+
+  emit(onEvent, "phase_complete", {
+    phase: "convergence",
+    newFilesDiscovered: newFiles.length,
+    extraScannersRun: convergenceResults.length,
+  });
+
+  // ── Coverage Verification ───────────────────────────────────────
+  // Coverage is computed from CONFIRMED-READ files (via blackboard tool_call
+  // events), not from the seed set. This prevents overstating coverage when
+  // sub-agents hit budget limits before reading all assigned files.
+
+  emit(onEvent, "phase_start", { phase: "coverage_verify" });
+
+  // Collect confirmed-read files from sub-agent results
+  const confirmedReadFiles = new Set();
+  for (const result of allResults) {
+    // Sub-agents track which files they actually read via tool calls
+    if (result.findings) {
+      for (const f of result.findings) {
+        if (f.file) confirmedReadFiles.add(f.file);
+        // FileScanner results include discovered files
+        if (f.path) confirmedReadFiles.add(f.path);
+      }
+    }
+    // Also count any file explicitly tracked by agent usage
+    if (result.usage?.filesRead) {
+      for (const f of result.usage.filesRead) confirmedReadFiles.add(f);
+    }
+  }
+  // Add primary files only if they were in the confirmed set or no agents ran
+  const allScannedFiles = confirmedReadFiles.size > 0
+    ? confirmedReadFiles
+    : new Set([...primaryFiles, ...newFiles]);
+
+  // Use FrontendAnalyze to check what files should exist
+  let frameworkInfo = {};
+  try {
+    frameworkInfo = frontendAnalyze({ operation: "detect_framework", path: rootPath });
+  } catch { /* proceed without framework info */ }
+
+  let scopeGraphInfo = {};
+  try {
+    scopeGraphInfo = frontendAnalyze({ operation: "scope_graph", path: rootPath });
+  } catch { /* proceed without scope graph */ }
+
+  const expectedFrontendFiles = scopeGraphInfo.components || 0;
+  const coverageRatio = expectedFrontendFiles > 0
+    ? ((allScannedFiles.size / expectedFrontendFiles) * 100).toFixed(1)
+    : "N/A";
+
+  // Identify files that were assigned but not confirmed-read
+  const assignedButUnread = primaryFiles.filter(f => !confirmedReadFiles.has(f));
+  const missedFiles = assignedButUnread.length > 0 && confirmedReadFiles.size > 0
+    ? assignedButUnread
+    : [];
+
+  const coverageLedger = {
+    seedFilesAssigned: primaryFiles.length,
+    confirmedReadFiles: confirmedReadFiles.size,
+    expandedFilesDiscovered: newFiles.length,
+    totalFilesReviewed: allScannedFiles.size,
+    expectedFrontendFiles,
+    coverageRatio,
+    missedFiles,
+    coverageMethod: confirmedReadFiles.size > 0 ? "confirmed_read" : "seed_based_fallback",
+  };
+
+  emit(onEvent, "phase_complete", {
+    phase: "coverage_verify",
+    coverage: coverageLedger,
+  });
+
+  // ── Build Swarm Result ──────────────────────────────────────────
+
+  const totalFindings = allResults.reduce((s, r) => s + r.findings.length, 0);
+  const totalCost = allResults.reduce((s, r) => s + (r.usage?.costUsd || 0), 0);
+  const totalToolCalls = allResults.reduce((s, r) => s + (r.usage?.toolCalls || 0), 0);
+  const durationMs = Date.now() - startedAt;
+
+  const result = {
+    runId,
+    status: "completed",
+    framework: frameworkInfo.framework || "unknown",
+    phases: {
+      fileScanning: { agents: scanResults.length, findings: scanResults.reduce((s, r) => s + r.findings.length, 0) },
+      patternHunting: { agents: huntResults.length, findings: huntResults.reduce((s, r) => s + r.findings.length, 0) },
+      convergence: { newFiles: newFiles.length, extraScanners: convergenceResults.length },
+    },
+    coverage: coverageLedger,
+    findings: {
+      total: totalFindings,
+      byAgent: allResults.map(r => ({ agentId: r.agentId, role: r.role, count: r.findings.length })),
+    },
+    usage: {
+      totalAgents: allResults.length,
+      totalCostUsd: totalCost,
+      totalToolCalls,
+      totalDurationMs: durationMs,
+    },
+    agentResults: allResults,
+  };
+
+  emit(onEvent, "swarm_complete", {
+    runId,
+    totalFindings,
+    totalAgents: allResults.length,
+    totalCostUsd: totalCost,
+    durationMs,
+    coverageRatio,
+  });
+
+  return result;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function isFrontendFile(filePath) {
+  return /\.(tsx|jsx|vue|svelte|css|scss|less)$/.test(filePath);
+}
+
+function detectRouteGroups(files) {
+  const routeDirs = new Set();
+  for (const f of files) {
+    const filePath = f.path || f;
+    const match = filePath.match(/(?:app|pages)\/([^/]+)/);
+    if (match) routeDirs.add(match[1]);
+  }
+  return [...routeDirs];
+}
+
+function partitionFiles(files, maxPerPartition) {
+  const partitions = [];
+  for (let i = 0; i < files.length; i += maxPerPartition) {
+    partitions.push(files.slice(i, i + maxPerPartition));
+  }
+  return partitions;
+}
+
+function divideBudget(totalBudget, agentCount) {
+  if (agentCount <= 0) return totalBudget;
+  return {
+    maxCostUsd: (totalBudget.maxCostUsd || 5) / agentCount,
+    maxOutputTokens: Math.floor((totalBudget.maxOutputTokens || 12000) / agentCount),
+    maxRuntimeMs: totalBudget.maxRuntimeMs || 300000,
+    maxToolCalls: Math.floor((totalBudget.maxToolCalls || 150) / agentCount),
+    warningThresholdPercent: totalBudget.warningThresholdPercent || 70,
+  };
+}
+
+function collectDiscoveredDeps(scanResults) {
+  const deps = new Set();
+  for (const result of scanResults) {
+    for (const finding of result.findings) {
+      if (finding.discoveredDependencies) {
+        for (const dep of finding.discoveredDependencies) {
+          if (typeof dep === "string" && dep.startsWith(".")) {
+            deps.add(dep);
+          }
+        }
+      }
+    }
+  }
+  return [...deps];
+}
+
+function emit(onEvent, event, payload) {
+  if (onEvent) {
+    onEvent({
+      stream: "sl_event",
+      event,
+      agent: { id: "frontend", persona: "Jules Tanaka", color: "cyan", avatar: "\u{1F3AF}" },
+      payload,
+    });
+  }
+}