sentinelayer-cli 0.1.0

package/src/swarm/registry.js

@@ -0,0 +1,419 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+const DEFAULT_BUDGET = Object.freeze({
+  maxCostUsd: 0.5,
+  maxOutputTokens: 3000,
+  maxRuntimeMs: 300000,
+  maxToolCalls: 40,
+});
+
+const BUILTIN_SWARM_AGENTS = Object.freeze([
+  {
+    id: "omar",
+    persona: "Omar Gate",
+    role: "orchestrator",
+    domain: "Autonomous Governance",
+    tools: ["planner", "budget-governor", "handoff-router"],
+    permissionMode: "plan",
+    maxTurns: 12,
+    confidenceFloor: 0.9,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: {
+      maxCostUsd: 1.5,
+      maxOutputTokens: 10000,
+      maxRuntimeMs: 900000,
+      maxToolCalls: 120,
+    },
+    evidenceRequirements: ["scope_constraints", "handoff_manifest", "gate_decision"],
+    escalationTargets: ["security", "reliability", "release"],
+  },
+  {
+    id: "security",
+    persona: "Nina Patel",
+    role: "specialist",
+    domain: "Security",
+    tools: ["read", "grep", "dependency-audit"],
+    permissionMode: "plan",
+    maxTurns: 8,
+    confidenceFloor: 0.85,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: {
+      maxCostUsd: 0.8,
+      maxOutputTokens: 4000,
+      maxRuntimeMs: 480000,
+      maxToolCalls: 60,
+    },
+    evidenceRequirements: ["file_line_reference", "repro_steps"],
+    escalationTargets: ["release", "reliability"],
+  },
+  {
+    id: "architecture",
+    persona: "Maya Volkov",
+    role: "specialist",
+    domain: "Architecture",
+    tools: ["read", "grep", "structure-map"],
+    permissionMode: "plan",
+    maxTurns: 8,
+    confidenceFloor: 0.82,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["component_map", "impact_summary"],
+    escalationTargets: ["performance", "testing"],
+  },
+  {
+    id: "testing",
+    persona: "Priya Raman",
+    role: "specialist",
+    domain: "Testing",
+    tools: ["read", "grep", "test-runner"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.8,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["coverage_gaps", "failing_paths"],
+    escalationTargets: ["architecture"],
+  },
+  {
+    id: "performance",
+    persona: "Arjun Mehta",
+    role: "specialist",
+    domain: "Performance",
+    tools: ["read", "grep", "profiler-hints"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.8,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["latency_paths", "runtime_assumptions"],
+    escalationTargets: ["architecture", "reliability"],
+  },
+  {
+    id: "compliance",
+    persona: "Leila Farouk",
+    role: "specialist",
+    domain: "Compliance",
+    tools: ["read", "grep", "control-map"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.82,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["control_refs", "evidence_paths"],
+    escalationTargets: ["security", "release"],
+  },
+  {
+    id: "documentation",
+    persona: "Samir Okafor",
+    role: "specialist",
+    domain: "Documentation",
+    tools: ["read", "grep", "spec-check"],
+    permissionMode: "plan",
+    maxTurns: 5,
+    confidenceFloor: 0.75,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: {
+      maxCostUsd: 0.35,
+      maxOutputTokens: 2500,
+      maxRuntimeMs: 240000,
+      maxToolCalls: 30,
+    },
+    evidenceRequirements: ["doc_paths", "spec_mismatches"],
+    escalationTargets: ["architecture", "release"],
+  },
+  {
+    id: "reliability",
+    persona: "Noah Ben-David",
+    role: "specialist",
+    domain: "Reliability",
+    tools: ["read", "grep", "failure-analysis"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.8,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["failure_modes", "rollback_plan"],
+    escalationTargets: ["release", "observability"],
+  },
+  {
+    id: "release",
+    persona: "Omar Singh",
+    role: "specialist",
+    domain: "Release Engineering",
+    tools: ["read", "grep", "workflow-review"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.8,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["workflow_refs", "gate_matrix"],
+    escalationTargets: ["security", "reliability"],
+  },
+  {
+    id: "observability",
+    persona: "Sofia Alvarez",
+    role: "specialist",
+    domain: "Observability",
+    tools: ["read", "grep", "telemetry-review"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.78,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["signal_inventory", "gaps"],
+    escalationTargets: ["reliability", "release"],
+  },
+  {
+    id: "infrastructure",
+    persona: "Kat Hughes",
+    role: "specialist",
+    domain: "Infrastructure",
+    tools: ["read", "grep", "infra-lint"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.78,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["infra_paths", "blast_radius"],
+    escalationTargets: ["security", "reliability"],
+  },
+  {
+    id: "supply-chain",
+    persona: "Nora Kline",
+    role: "specialist",
+    domain: "Supply Chain",
+    tools: ["read", "grep", "dependency-audit"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.82,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["dependency_refs", "version_risks"],
+    escalationTargets: ["security", "release"],
+  },
+  {
+    id: "frontend",
+    persona: "Jules Tanaka",
+    role: "specialist",
+    domain: "Frontend",
+    tools: ["read", "grep", "ui-lint"],
+    permissionMode: "plan",
+    maxTurns: 6,
+    confidenceFloor: 0.76,
+    allowedPaths: ["."],
+    networkMode: "restricted",
+    defaultBudget: { ...DEFAULT_BUDGET },
+    evidenceRequirements: ["component_paths", "repro_steps"],
+    escalationTargets: ["testing", "architecture"],
+  },
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeAgentId(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function normalizeRole(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (normalized === "orchestrator" || normalized === "specialist") {
+    return normalized;
+  }
+  return "specialist";
+}
+
+function normalizeNetworkMode(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (normalized === "enabled" || normalized === "restricted" || normalized === "disabled") {
+    return normalized;
+  }
+  return "restricted";
+}
+
+function normalizePositiveNumber(value, fallback, field) {
+  const normalized = Number(value);
+  if (Number.isFinite(normalized) && normalized > 0) {
+    return normalized;
+  }
+  if (fallback !== undefined) {
+    return Number(fallback);
+  }
+  throw new Error(`${field} must be a positive number.`);
+}
+
+function normalizeBudget(budget = {}, fallback = DEFAULT_BUDGET) {
+  if (budget === undefined || budget === null || typeof budget !== "object" || Array.isArray(budget)) {
+    throw new Error("defaultBudget must be an object when provided.");
+  }
+
+  return {
+    maxCostUsd: normalizePositiveNumber(
+      budget.maxCostUsd,
+      fallback.maxCostUsd,
+      "defaultBudget.maxCostUsd"
+    ),
+    maxOutputTokens: Math.floor(
+      normalizePositiveNumber(
+        budget.maxOutputTokens,
+        fallback.maxOutputTokens,
+        "defaultBudget.maxOutputTokens"
+      )
+    ),
+    maxRuntimeMs: Math.floor(
+      normalizePositiveNumber(
+        budget.maxRuntimeMs,
+        fallback.maxRuntimeMs,
+        "defaultBudget.maxRuntimeMs"
+      )
+    ),
+    maxToolCalls: Math.floor(
+      normalizePositiveNumber(
+        budget.maxToolCalls,
+        fallback.maxToolCalls,
+        "defaultBudget.maxToolCalls"
+      )
+    ),
+  };
+}
+
+function normalizeAgentRecord(record = {}, existing = {}) {
+  const id = normalizeAgentId(record.id || existing.id);
+  const fallbackBudget = existing.defaultBudget || DEFAULT_BUDGET;
+
+  return {
+    id,
+    persona: normalizeString(record.persona || existing.persona),
+    role: normalizeRole(record.role || existing.role),
+    domain: normalizeString(record.domain || existing.domain),
+    tools: Array.isArray(record.tools || existing.tools)
+      ? (record.tools || existing.tools).map((item) => normalizeString(item)).filter(Boolean)
+      : [],
+    permissionMode: normalizeString(record.permissionMode || existing.permissionMode || "plan") || "plan",
+    maxTurns: Math.max(1, Math.floor(Number(record.maxTurns || existing.maxTurns || 1))),
+    confidenceFloor: Math.max(
+      0,
+      Math.min(1, Number(record.confidenceFloor || existing.confidenceFloor || 0.7))
+    ),
+    allowedPaths: Array.isArray(record.allowedPaths || existing.allowedPaths)
+      ? (record.allowedPaths || existing.allowedPaths).map((item) => normalizeString(item)).filter(Boolean)
+      : ["."],
+    networkMode: normalizeNetworkMode(record.networkMode || existing.networkMode),
+    defaultBudget: normalizeBudget(record.defaultBudget || existing.defaultBudget || {}, fallbackBudget),
+    evidenceRequirements: Array.isArray(record.evidenceRequirements || existing.evidenceRequirements)
+      ? (record.evidenceRequirements || existing.evidenceRequirements)
+          .map((item) => normalizeString(item))
+          .filter(Boolean)
+      : [],
+    escalationTargets: Array.isArray(record.escalationTargets || existing.escalationTargets)
+      ? (record.escalationTargets || existing.escalationTargets)
+          .map((item) => normalizeAgentId(item))
+          .filter(Boolean)
+      : [],
+  };
+}
+
+function mergeRegistry(builtinAgents = [], overrideAgents = []) {
+  const byId = new Map();
+  const order = [];
+
+  for (const builtin of builtinAgents) {
+    const normalized = normalizeAgentRecord(builtin);
+    byId.set(normalized.id, normalized);
+    order.push(normalized.id);
+  }
+
+  for (const override of overrideAgents) {
+    const id = normalizeAgentId(override.id);
+    if (!id) {
+      continue;
+    }
+    if (!byId.has(id)) {
+      order.push(id);
+    }
+    const existing = byId.get(id) || { id };
+    byId.set(id, normalizeAgentRecord(override, existing));
+  }
+
+  return order.map((id) => ({ ...byId.get(id) })).filter(Boolean);
+}
+
+function parseAgentFilter(rawValue) {
+  const normalized = normalizeString(rawValue);
+  if (!normalized) {
+    return [];
+  }
+  return [...new Set(normalized.split(",").map((item) => normalizeAgentId(item)).filter(Boolean))];
+}
+
+export function listBuiltinSwarmAgents() {
+  return BUILTIN_SWARM_AGENTS.map((agent) => normalizeAgentRecord(agent));
+}
+
+export async function loadSwarmRegistry({ registryFile = "" } = {}) {
+  const builtin = listBuiltinSwarmAgents();
+  const resolvedRegistryFile = normalizeString(registryFile)
+    ? path.resolve(process.cwd(), registryFile)
+    : "";
+  if (!resolvedRegistryFile) {
+    return {
+      registrySource: "builtin",
+      registryFile: "",
+      agents: builtin,
+    };
+  }
+
+  const raw = await fsp.readFile(resolvedRegistryFile, "utf-8");
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.agents)) {
+    throw new Error("Invalid swarm registry file: expected { agents: [...] }.");
+  }
+
+  return {
+    registrySource: "custom",
+    registryFile: resolvedRegistryFile,
+    agents: mergeRegistry(builtin, parsed.agents),
+  };
+}
+
+export function selectSwarmAgents(agents = [], requested = "") {
+  const requestedIds = parseAgentFilter(requested);
+  if (requestedIds.length === 0) {
+    return {
+      selected: [...agents],
+      requestedIds,
+      missing: [],
+    };
+  }
+
+  const byId = new Map(agents.map((agent) => [agent.id, agent]));
+  const selected = [];
+  const missing = [];
+  for (const id of requestedIds) {
+    const agent = byId.get(id);
+    if (!agent) {
+      missing.push(id);
+      continue;
+    }
+    selected.push(agent);
+  }
+  return {
+    selected,
+    requestedIds,
+    missing,
+  };
+}

package/src/swarm/report.js

@@ -0,0 +1,158 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { resolveOutputRoot } from "../config/service.js";
+import { loadSwarmDashboardSnapshot, resolveSwarmRuntimeFiles } from "./dashboard.js";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fsp.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function summarizeAgents(agentRows = []) {
+  const summary = {
+    completed: 0,
+    running: 0,
+    stopped: 0,
+    unknown: 0,
+  };
+  for (const row of agentRows) {
+    const status = normalizeString(row.status).toLowerCase();
+    if (status === "completed") {
+      summary.completed += 1;
+      continue;
+    }
+    if (status === "running") {
+      summary.running += 1;
+      continue;
+    }
+    if (status === "stopped") {
+      summary.stopped += 1;
+      continue;
+    }
+    summary.unknown += 1;
+  }
+  return summary;
+}
+
+function buildReportMarkdown(report = {}) {
+  const agentRows = (report.agentRows || [])
+    .map(
+      (row) =>
+        `- ${row.agentId} status=${row.status} events=${row.eventCount} last=${row.lastEventType || "n/a"}`
+    )
+    .join("\n");
+  const recentEvents = (report.recentEvents || [])
+    .map((event) => `- ${event.timestamp} [${event.eventType}] ${event.agentId}: ${event.message}`)
+    .join("\n");
+
+  return `# SWARM_EXECUTION_REPORT
+
+Generated: ${report.generatedAt}
+Runtime run ID: ${report.runtimeRunId}
+Plan run ID: ${report.planRunId || "n/a"}
+Scenario: ${report.scenario}
+Engine: ${report.engine}
+Execute: ${report.execute ? "yes" : "no"}
+Completed: ${report.completed ? "yes" : "no"}
+Stop class: ${report.stop?.stopClass || "NONE"}
+Stop reason: ${report.stop?.reason || "none"}
+
+Usage:
+- output_tokens: ${report.usage.outputTokens || 0}
+- tool_calls: ${report.usage.toolCalls || 0}
+- duration_ms: ${report.usage.durationMs || 0}
+- cost_usd: ${report.usage.costUsd || 0}
+
+Agents:
+${agentRows || "- none"}
+
+Recent events:
+${recentEvents || "- none"}
+
+Artifacts:
+- runtime_json: ${report.runtimeJsonPath}
+- runtime_events: ${report.runtimeEventsPath}
+- plan_json: ${report.planJsonPath || "n/a"}
+- report_json: ${report.reportJsonPath}
+`;
+}
+
+export async function buildSwarmExecutionReport({
+  targetPath = ".",
+  outputDir = "",
+  runId = "",
+  planFile = "",
+  env,
+  homeDir,
+} = {}) {
+  const files = await resolveSwarmRuntimeFiles({
+    targetPath,
+    outputDir,
+    runId,
+    env,
+    homeDir,
+  });
+  const snapshot = await loadSwarmDashboardSnapshot({
+    targetPath,
+    outputDir,
+    runId: files.runId,
+    env,
+    homeDir,
+  });
+
+  const outputRoot = await resolveOutputRoot({
+    cwd: path.resolve(String(targetPath || ".")),
+    outputDirOverride: outputDir,
+    env,
+    homeDir,
+  });
+
+  const runtimeSummary = JSON.parse(await fsp.readFile(files.runtimeJsonPath, "utf-8"));
+  const selectedPlanPath = normalizeString(planFile)
+    ? path.resolve(process.cwd(), planFile)
+    : path.join(outputRoot, "swarms", normalizeString(runtimeSummary.planRunId), "SWARM_PLAN.json");
+  const planJsonPath = (await pathExists(selectedPlanPath)) ? selectedPlanPath : "";
+  const plan = planJsonPath ? JSON.parse(await fsp.readFile(planJsonPath, "utf-8")) : null;
+
+  const reportJsonPath = path.join(files.runtimeDirectory, "SWARM_EXECUTION_REPORT.json");
+  const reportMarkdownPath = path.join(files.runtimeDirectory, "SWARM_EXECUTION_REPORT.md");
+  const report = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    runtimeRunId: runtimeSummary.runId,
+    planRunId: normalizeString(runtimeSummary.planRunId),
+    scenario: runtimeSummary.scenario,
+    engine: runtimeSummary.engine,
+    execute: Boolean(runtimeSummary.execute),
+    completed: Boolean(runtimeSummary.completed),
+    stop: runtimeSummary.stop || {
+      stopClass: "NONE",
+      reason: "",
+      blocking: false,
+    },
+    usage: runtimeSummary.usage || {},
+    eventCount: runtimeSummary.eventCount || snapshot.eventCount,
+    agentRows: snapshot.agentRows,
+    agentSummary: summarizeAgents(snapshot.agentRows),
+    recentEvents: snapshot.recentEvents,
+    runtimeJsonPath: files.runtimeJsonPath,
+    runtimeEventsPath: files.runtimeEventsPath,
+    planJsonPath,
+    planSelectedAgents: Array.isArray(plan?.selectedAgents) ? plan.selectedAgents : [],
+    reportJsonPath,
+    reportMarkdownPath,
+  };
+
+  await fsp.writeFile(reportJsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
+  await fsp.writeFile(reportMarkdownPath, `${buildReportMarkdown(report).trim()}\n`, "utf-8");
+  return report;
+}