sentinelayer-cli 0.6.2 → 0.8.1

package/src/agents/jules/tools/shell.js

@@ -1,2 +1,2 @@
-// Re-export from shared tools. Shell is not Jules-specific.
-export { shell, analyzeCommand, buildScrubbedEnv, ShellError, ShellBlockedError } from "../../shared-tools/shell.js";
+// Re-export from shared tools. Shell is not Jules-specific.
+export { shell, analyzeCommand, buildScrubbedEnv, ShellError, ShellBlockedError } from "../../shared-tools/shell.js";

package/src/agents/jules/tools/url-policy.js

@@ -1,100 +1,100 @@
-const PRIVATE_HOST_SUFFIXES = [".internal", ".local", ".localhost"];
-const BLOCKED_LITERAL_HOSTS = new Set([
-  "localhost",
-  "127.0.0.1",
-  "::1",
-  "0.0.0.0",
-  "169.254.169.254",
-  "metadata.google.internal",
-  "metadata.google.internal.",
-]);
-
-function isNumericIpv4(hostname) {
-  const parts = String(hostname || "").split(".");
-  if (parts.length !== 4) {
-    return false;
-  }
-  return parts.every((part) => /^[0-9]{1,3}$/.test(part) && Number(part) >= 0 && Number(part) <= 255);
-}
-
-function isPrivateIpv4(hostname) {
-  if (!isNumericIpv4(hostname)) {
-    return false;
-  }
-  const parts = hostname.split(".").map((part) => Number(part));
-  const [a, b] = parts;
-  if (a === 10 || a === 127 || a === 0) return true;
-  if (a === 169 && b === 254) return true;
-  if (a === 172 && b >= 16 && b <= 31) return true;
-  if (a === 192 && b === 168) return true;
-  if (a === 100 && b >= 64 && b <= 127) return true;
-  if (a === 198 && (b === 18 || b === 19)) return true;
-  return false;
-}
-
-function isPrivateIpv6(hostname) {
-  const normalized = String(hostname || "").toLowerCase().split("%")[0];
-  if (!normalized.includes(":")) {
-    return false;
-  }
-  if (normalized === "::1" || normalized === "::") {
-    return true;
-  }
-  if (normalized.startsWith("fc") || normalized.startsWith("fd")) {
-    return true;
-  }
-  if (normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb")) {
-    return true;
-  }
-  return false;
-}
-
-function isPrivateHostname(hostname) {
-  const normalized = String(hostname || "").toLowerCase();
-  if (!normalized) {
-    return true;
-  }
-  if (BLOCKED_LITERAL_HOSTS.has(normalized)) {
-    return true;
-  }
-  if (PRIVATE_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
-    return true;
-  }
-  if (isPrivateIpv4(normalized) || isPrivateIpv6(normalized)) {
-    return true;
-  }
-  return false;
-}
-
-function isPrivateTargetBypassEnabled(allowPrivateTargets) {
-  if (allowPrivateTargets === true) {
-    return true;
-  }
-  if (process.env.SENTINELAYER_ALLOW_PRIVATE_AUDIT_TARGETS === "1") {
-    return true;
-  }
-  if (process.env.NODE_ENV === "test") {
-    return true;
-  }
-  return false;
-}
-
-export function assertPermittedAuditTarget(urlValue, options = {}) {
-  const { operation = "audit", allowPrivateTargets = false } = options;
-  let parsed;
-  try {
-    parsed = new URL(urlValue);
-  } catch {
-    throw new Error("Invalid URL: " + urlValue);
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error("Invalid URL: " + parsed.toString());
-  }
-  if (!isPrivateTargetBypassEnabled(allowPrivateTargets) && isPrivateHostname(parsed.hostname)) {
-    throw new Error(
-      `Blocked private audit target for ${operation}: ${parsed.hostname}. ` +
-      "Set allowPrivateTargets=true or SENTINELAYER_ALLOW_PRIVATE_AUDIT_TARGETS=1 to override."
-    );
-  }
-  return parsed;
-}
+const PRIVATE_HOST_SUFFIXES = [".internal", ".local", ".localhost"];
+const BLOCKED_LITERAL_HOSTS = new Set([
+  "localhost",
+  "127.0.0.1",
+  "::1",
+  "0.0.0.0",
+  "169.254.169.254",
+  "metadata.google.internal",
+  "metadata.google.internal.",
+]);
+
+function isNumericIpv4(hostname) {
+  const parts = String(hostname || "").split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  return parts.every((part) => /^[0-9]{1,3}$/.test(part) && Number(part) >= 0 && Number(part) <= 255);
+}
+
+function isPrivateIpv4(hostname) {
+  if (!isNumericIpv4(hostname)) {
+    return false;
+  }
+  const parts = hostname.split(".").map((part) => Number(part));
+  const [a, b] = parts;
+  if (a === 10 || a === 127 || a === 0) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  return false;
+}
+
+function isPrivateIpv6(hostname) {
+  const normalized = String(hostname || "").toLowerCase().split("%")[0];
+  if (!normalized.includes(":")) {
+    return false;
+  }
+  if (normalized === "::1" || normalized === "::") {
+    return true;
+  }
+  if (normalized.startsWith("fc") || normalized.startsWith("fd")) {
+    return true;
+  }
+  if (normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb")) {
+    return true;
+  }
+  return false;
+}
+
+function isPrivateHostname(hostname) {
+  const normalized = String(hostname || "").toLowerCase();
+  if (!normalized) {
+    return true;
+  }
+  if (BLOCKED_LITERAL_HOSTS.has(normalized)) {
+    return true;
+  }
+  if (PRIVATE_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+    return true;
+  }
+  if (isPrivateIpv4(normalized) || isPrivateIpv6(normalized)) {
+    return true;
+  }
+  return false;
+}
+
+function isPrivateTargetBypassEnabled(allowPrivateTargets) {
+  if (allowPrivateTargets === true) {
+    return true;
+  }
+  if (process.env.SENTINELAYER_ALLOW_PRIVATE_AUDIT_TARGETS === "1") {
+    return true;
+  }
+  if (process.env.NODE_ENV === "test") {
+    return true;
+  }
+  return false;
+}
+
+export function assertPermittedAuditTarget(urlValue, options = {}) {
+  const { operation = "audit", allowPrivateTargets = false } = options;
+  let parsed;
+  try {
+    parsed = new URL(urlValue);
+  } catch {
+    throw new Error("Invalid URL: " + urlValue);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Invalid URL: " + parsed.toString());
+  }
+  if (!isPrivateTargetBypassEnabled(allowPrivateTargets) && isPrivateHostname(parsed.hostname)) {
+    throw new Error(
+      `Blocked private audit target for ${operation}: ${parsed.hostname}. ` +
+      "Set allowPrivateTargets=true or SENTINELAYER_ALLOW_PRIVATE_AUDIT_TARGETS=1 to override."
+    );
+  }
+  return parsed;
+}

package/src/agents/mode.js

@@ -0,0 +1,113 @@
+// Persona mode selector (#A27, spec §Phase 5 / PR #A27).
+//
+// The persona envelope (PR #A8) is identical between audit and code-gen
+// modes. The only per-mode variation:
+//   1. The allowed-tools subset. Audit gets read-only tools + domain scans.
+//      Codegen gets the read-only tools PLUS file-edit + shell (sandboxed)
+//      so the persona can apply fixes.
+//   2. The system-prompt suffix. Audit mode appends "Emit findings only.
+//      Do not modify files." Codegen mode appends "Apply fixes as minimal
+//      edits with clear commit-message summaries."
+//
+// This module is the single source of truth for those two deltas. Every
+// caller that spawns a persona does so through `buildPersonaConfigForMode`;
+// same persona, same domain tools, same budget knobs — only the two deltas
+// change.
+
+// Persona tool id lists are inlined here instead of imported from each
+// persona module. Rationale: this module has to be importable before all
+// 12 persona PRs (#A13-A24) have merged to main. Once they do, a future
+// refactor can swap these for real imports — the tool-id strings are
+// stable anyway.
+
+export const PERSONA_MODES = Object.freeze(["audit", "codegen"]);
+
+// Read-only tool ids that exist in every persona — the audit baseline.
+// When a persona is invoked in `audit` mode, it gets the union of its own
+// domain tools and these shared scanners. Code-gen mode adds the edit /
+// shell tools below on top.
+const READONLY_BASELINE = Object.freeze([
+  "FileRead",
+  "Grep",
+  "Glob",
+]);
+
+const CODEGEN_EXTRA_TOOLS = Object.freeze([
+  "FileEdit",
+  "Shell",
+]);
+
+const DOMAIN_TOOL_IDS_BY_PERSONA = Object.freeze({
+  "ai-governance": Object.freeze(["eval-regression", "hitl-audit", "prompt-drift", "provenance-check"]),
+  "backend": Object.freeze(["circuit-breaker-check", "idempotency-audit", "retry-audit", "timeout-audit"]),
+  "code-quality": Object.freeze(["complexity-measure", "coupling-analysis", "cycle-detect", "dep-graph"]),
+  "data-layer": Object.freeze(["index-audit", "migration-scan", "query-explain", "tenancy-scan"]),
+  "documentation": Object.freeze(["api-diff", "dead-link-check", "docstring-coverage", "readme-freshness"]),
+  "infrastructure": Object.freeze(["checkov-run", "drift-detect", "iam-least-priv-check", "tflint-run"]),
+  "observability": Object.freeze(["alert-audit", "dashboard-gap", "log-schema-check", "span-coverage"]),
+  "release": Object.freeze(["changelog-diff", "feature-flag-audit", "rollback-verify", "semver-check"]),
+  "reliability": Object.freeze(["backpressure-check", "chaos-probe", "graceful-degradation-check", "health-check-audit"]),
+  "security": Object.freeze(["authz-audit", "crypto-review", "sast-scan", "secrets-scan"]),
+  "supply-chain": Object.freeze(["attestation-check", "lockfile-integrity", "package-verify", "sbom-diff"]),
+  "testing": Object.freeze(["coverage-gap", "flake-detect", "mutation-test", "snapshot-diff"]),
+});
+
+const MODE_PROMPT_SUFFIXES = Object.freeze({
+  audit: [
+    "",
+    "You are operating in AUDIT mode.",
+    "Emit findings only. Do not modify files. Your output is structured JSON that downstream tooling will rank, dedupe, and present to the reviewer.",
+    "When you call a domain tool, the tool writes Finding objects. You decide which of those to elevate into your final report and how to prioritize them.",
+  ].join("\n"),
+  codegen: [
+    "",
+    "You are operating in CODE-GEN mode.",
+    "Apply fixes as minimal, reviewable edits. Every file you touch must compile / parse; every change should include a one-line commit-message-style rationale.",
+    "When you call a domain tool, treat the resulting Finding list as the work queue. Your output is a set of file edits plus an explanation of what you did and what you deliberately left for a human.",
+  ].join("\n"),
+});
+
+export function normalizePersonaMode(mode) {
+  const normalized = String(mode || "").trim().toLowerCase();
+  if (PERSONA_MODES.includes(normalized)) {
+    return normalized;
+  }
+  return "audit";
+}
+
+// Return { mode, allowedTools, promptSuffix, personaId } for a persona in
+// the requested mode. The only values that depend on mode are allowedTools
+// and promptSuffix; everything else (budget, identity, system prompt body)
+// is supplied by the persona's own definition.
+export function buildPersonaConfigForMode(personaId, mode) {
+  const normalizedMode = normalizePersonaMode(mode);
+  const normalizedPersona = String(personaId || "").trim().toLowerCase();
+  const domainTools = DOMAIN_TOOL_IDS_BY_PERSONA[normalizedPersona] || [];
+
+  const allowedTools = new Set([...READONLY_BASELINE, ...domainTools]);
+  if (normalizedMode === "codegen") {
+    for (const tool of CODEGEN_EXTRA_TOOLS) {
+      allowedTools.add(tool);
+    }
+  }
+  return {
+    personaId: normalizedPersona,
+    mode: normalizedMode,
+    allowedTools: Array.from(allowedTools),
+    promptSuffix: MODE_PROMPT_SUFFIXES[normalizedMode],
+  };
+}
+
+// Quick boolean for callers that just want "can this mode write files?"
+export function modeAllowsWrites(mode) {
+  return normalizePersonaMode(mode) === "codegen";
+}
+
+// Which personas does the mode selector recognize? Useful for tests /
+// diagnostics — callers can detect a typo in a persona id before they
+// dispatch.
+export function listKnownPersonaIds() {
+  return Object.keys(DOMAIN_TOOL_IDS_BY_PERSONA).slice().sort();
+}
+
+export { READONLY_BASELINE, CODEGEN_EXTRA_TOOLS, MODE_PROMPT_SUFFIXES };

package/src/agents/observability/index.js

@@ -0,0 +1,12 @@
+// Sofia (observability persona) — barrel export (#A20).
+
+export {
+  OBSERVABILITY_TOOLS,
+  OBSERVABILITY_TOOL_IDS,
+  dispatchObservabilityTool,
+  runAllObservabilityTools,
+  runAlertAudit,
+  runDashboardGap,
+  runLogSchemaCheck,
+  runSpanCoverage,
+} from "./tools/index.js";

package/src/agents/observability/tools/alert-audit.js

@@ -0,0 +1,39 @@
+// alert-audit — check that alert definitions exist (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const ALERT_SIGNATURES = [
+  /(^|\/)alerts?\/[^/]+\.(ya?ml|json|tf)$/i,
+  /(^|\/)prometheus\/rules?\//i,
+  /(^|\/)alertmanager\//i,
+  /(^|\/)monitors?\/[^/]+\.(ya?ml|json|tf)$/i,
+];
+
+export async function runAlertAudit({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  let found = false;
+  for await (const { relativePath } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (ALERT_SIGNATURES.some((p) => p.test(rel))) {
+      found = true;
+      break;
+    }
+  }
+  if (found) return [];
+  return [
+    createFinding({
+      tool: "alert-audit",
+      kind: "observability.no-alerts",
+      severity: "P2",
+      file: "",
+      line: 0,
+      evidence: "No alert definitions found under alerts/, monitors/, prometheus/rules/, or alertmanager/",
+      rootCause: "Without declarative alert definitions we can't tell what production failures the team is actually notified of.",
+      recommendedFix: "Define alerts in code (Prometheus rules, Datadog Terraform monitors, SLO burn-rate alerts). Require every critical endpoint to have an error-rate + latency alert.",
+      confidence: 0.6,
+    }),
+  ];
+}

package/src/agents/observability/tools/base.js

@@ -0,0 +1,181 @@
+// Shared helpers for Sofia's (observability) domain tools (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import ignore from "ignore";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".sentinelayer",
+  ".sentinel",
+  ".turbo",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".cache",
+]);
+const MAX_FILE_SIZE_BYTES = 1024 * 1024;
+const SEVERITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
+
+export function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+export function normalizeSeverity(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (SEVERITIES.includes(normalized)) {
+    return normalized;
+  }
+  return "P2";
+}
+
+export function createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "observability",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "observability",
+    severity: normalizeSeverity(severity),
+    file: toPosix(file || ""),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence:
+      confidence === null || confidence === undefined
+        ? null
+        : Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+async function readIgnorePatterns(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return String(raw || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+async function createIgnoreMatcher(rootPath) {
+  const matcher = ignore();
+  const gitignore = await readIgnorePatterns(path.join(rootPath, ".gitignore"));
+  const sentinel = await readIgnorePatterns(
+    path.join(rootPath, ".sentinelayerignore")
+  );
+  matcher.add([...gitignore, ...sentinel]);
+  return (relativePath, isDirectory) => {
+    const normalized = toPosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    const candidate = isDirectory ? `${normalized}/` : normalized;
+    return matcher.ignores(candidate);
+  };
+}
+
+export async function* walkRepoFiles({
+  rootPath = process.cwd(),
+  extensions = new Set(),
+  maxFileSize = MAX_FILE_SIZE_BYTES,
+} = {}) {
+  const resolvedRoot = path.resolve(rootPath);
+  const ignoreMatcher = await createIgnoreMatcher(resolvedRoot);
+  const wantedExtensions =
+    extensions instanceof Set
+      ? extensions
+      : new Set(Array.isArray(extensions) ? extensions : []);
+  const stack = [resolvedRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = toPosix(path.relative(resolvedRoot, fullPath));
+      if (entry.isDirectory()) {
+        if (!relativePath || DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (ignoreMatcher(relativePath, true)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (ignoreMatcher(relativePath, false)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (wantedExtensions.size > 0 && !wantedExtensions.has(ext) && !wantedExtensions.has("")) {
+        continue;
+      }
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      if (!stat || stat.size > maxFileSize) {
+        continue;
+      }
+      yield { fullPath, relativePath };
+    }
+  }
+}
+
+export function findLineMatches(content, pattern) {
+  const text = String(content || "");
+  if (!pattern) {
+    return [];
+  }
+  const global = new RegExp(
+    pattern.source,
+    pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
+  );
+  const matches = [];
+  let match;
+  while ((match = global.exec(text)) !== null) {
+    const lineIndex = text.slice(0, match.index).split(/\r?\n/).length;
+    matches.push({ index: match.index, line: lineIndex, match: match[0] });
+  }
+  return matches;
+}
+
+export function getLineContent(content, line) {
+  const lines = String(content || "").split(/\r?\n/);
+  return (lines[Math.max(0, (Number(line) || 1) - 1)] || "").trim();
+}
+
+export { DEFAULT_IGNORED_DIRS, MAX_FILE_SIZE_BYTES, SEVERITIES };

package/src/agents/observability/tools/dashboard-gap.js

@@ -0,0 +1,42 @@
+// dashboard-gap — check that a dashboard config exists somewhere (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const MANIFEST_SIGNATURES = [
+  /(^|\/)dashboards?\//,
+  /(^|\/)grafana\//,
+  /(^|\/)datadog\//,
+  /(^|\/)observability\//,
+];
+const DASHBOARD_FILES = /\.json$|\.yaml$|\.yml$/i;
+
+export async function runDashboardGap({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  let found = false;
+  for await (const { relativePath } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (MANIFEST_SIGNATURES.some((p) => p.test(rel)) && DASHBOARD_FILES.test(rel)) {
+      found = true;
+      break;
+    }
+  }
+  if (found) {
+    return [];
+  }
+  return [
+    createFinding({
+      tool: "dashboard-gap",
+      kind: "observability.no-dashboard",
+      severity: "P3",
+      file: "",
+      line: 0,
+      evidence: "No dashboards/, grafana/, datadog/, or observability/ directory with JSON / YAML configs",
+      rootCause: "No dashboard config checked into the repo. Ad-hoc dashboards created in the UI are invisible to code review and drift over time.",
+      recommendedFix: "Check a machine-readable dashboard source (Grafana JSON, Datadog Terraform, OpenMetrics) into the repo. Generate the deployed dashboard from source to keep them in sync.",
+      confidence: 0.55,
+    }),
+  ];
+}

package/src/agents/observability/tools/index.js

@@ -0,0 +1,54 @@
+// Sofia (observability persona) domain-tool registry (#A20).
+
+import { runAlertAudit } from "./alert-audit.js";
+import { runDashboardGap } from "./dashboard-gap.js";
+import { runLogSchemaCheck } from "./log-schema-check.js";
+import { runSpanCoverage } from "./span-coverage.js";
+
+export const OBSERVABILITY_TOOLS = Object.freeze({
+  "span-coverage": {
+    id: "span-coverage",
+    description: "Flag route handlers that have no OpenTelemetry / Sentry / Datadog tracing span in scope.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runSpanCoverage,
+  },
+  "dashboard-gap": {
+    id: "dashboard-gap",
+    description: "Report if no dashboard configuration (Grafana JSON, Datadog TF, observability dir) is checked into the repo.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runDashboardGap,
+  },
+  "alert-audit": {
+    id: "alert-audit",
+    description: "Report if no declarative alert definitions (Prometheus rules, Datadog monitors, alertmanager) are checked in.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runAlertAudit,
+  },
+  "log-schema-check": {
+    id: "log-schema-check",
+    description: "Flag production source files (not tests / scripts / docs) that use console.log / print() instead of a structured logger.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runLogSchemaCheck,
+  },
+});
+
+export const OBSERVABILITY_TOOL_IDS = Object.freeze(Object.keys(OBSERVABILITY_TOOLS));
+
+export async function dispatchObservabilityTool(toolId, args = {}) {
+  const tool = OBSERVABILITY_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown observability tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllObservabilityTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of OBSERVABILITY_TOOL_IDS) {
+    const out = await dispatchObservabilityTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export { runAlertAudit, runDashboardGap, runLogSchemaCheck, runSpanCoverage };