@nuvlore/extension-bds 0.1.1

package/tools/bds_yarn_app_health_command_pack.mjs

@@ -0,0 +1,529 @@
+export const description = "Generate a atomic-helper, read-only BDS YARN application command pack for app timeout requests, aggregated log host discovery, NodeManager health, and DataNode cross-checks; does not SSH, run YARN, or inspect HDFS.";
+
+import { z } from "zod";
+import { defineReadOnlyTool, fail, ok } from "@nuvlore/extension-read-only-toolkit/devops-diagnostics";
+import { ReadOnlyStep, remoteCommandInput, shellQuote } from "@nuvlore/extension-read-only-toolkit/read-only-command-pack";
+
+const DEFAULT_LOG_ROOT = "hdfs://bdsashcustaz1/var/log/hadoop-yarn/apps";
+
+const SAFETY_RULES = [
+  "read-only only: yarn application -status, yarn logs metadata reads, hdfs dfs -ls/-du/-find, hdfs dfsadmin -report, and yarn node -status",
+  "ResourceManager ApplicationSummary reads are allowed for historical app state and failed-app lists when RM/Timeline retention has expired",
+  "historical incident-window checks must use read-only journalctl/grep/zgrep over kernel, NodeManager, and DataNode logs only",
+  "never run yarn application -kill, yarn node -decommission, hdfs dfs -rm, hdfs dfs -put, hdfs dfs -get, hdfs dfs -cp, hdfs dfs -mv, chmod, chown, service restart, or host mutation",
+  "do not fetch full aggregated yarn logs first; use -show_application_log_info, precise HDFS path discovery, and bounded grep/head/tail",
+  "treat RM/Timeline absence separately from filesystem log availability",
+  "never print LDAP passwords, Keychain payloads, tokens, or sudo stdin",
+  "pass sudo credentials through stdin only when the operator explicitly approved it"
+];
+
+const HISTORICAL_NOISE_FILTERS = [
+  "DFSUtil.*duration=0",
+  "Scheduling blk_",
+  "Deleted BP-",
+  "DataNode.clienttrace",
+  "PacketResponder:.*terminating",
+  "short GC pause detail lines; call out only long pauses, for example >= 1000 ms",
+  "minor NodeManager process-accounting WARNs after the incident window unless paired with health failures"
+];
+
+const hostSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .regex(/^(?!-)[a-zA-Z0-9._:@%-]+$/);
+
+const appIdSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^application_[0-9]+_[0-9]+$/);
+
+const clusterSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_.:-]+$/)
+  .optional();
+
+const principalSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_.@/-]+$/)
+  .default("workdayadmin");
+
+const keytabSchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .regex(/^\/[A-Za-z0-9._/-]+$/)
+  .default("/etc/hadoop/conf/workdayadmin.keytab");
+
+const pathSchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .regex(/^[A-Za-z0-9:._@%/-]+$/)
+  .default(DEFAULT_LOG_ROOT);
+
+const tenantSchema = z
+  .string()
+  .min(1)
+  .max(160)
+  .regex(/^[A-Za-z0-9_.-]+$/)
+  .optional();
+
+const ownerSchema = z
+  .string()
+  .min(1)
+  .max(160)
+  .regex(/^[A-Za-z0-9_.-]+$/)
+  .optional();
+
+const hostListSchema = z
+  .array(hostSchema)
+  .max(80)
+  .default([]);
+
+const utcTimestampSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}[ T][0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]{1,6})?)?(Z| UTC)?$/)
+  .optional();
+
+const minuteWindowSchema = z.number().int().min(1).max(30).default(2);
+
+function appBucket(appId) {
+  return appId.split("_").at(-1);
+}
+
+function hdfsGlobForKnownOwner({ logRoot, appOwner, appId }) {
+  const bucket = appBucket(appId);
+  return `${logRoot}/${appOwner}/{logs,logs-tfile,bucket-logs-tfile/${bucket}}/${appId}`;
+}
+
+function hdfsFindCommand(logRoot, appId) {
+  return `timeout 120s hdfs dfs -find ${shellQuote(logRoot)} -name ${shellQuote(`*${appId}*`)} 2>&1 | head -300`;
+}
+
+function parseUtcTimestamp(value) {
+  if (!value) return undefined;
+  const normalized = value
+    .replace(" ", "T")
+    .replace(/ UTC$/, "Z")
+    .replace(/(?<!Z)$/, value.endsWith("Z") || value.endsWith(" UTC") ? "" : "Z");
+  const date = new Date(normalized);
+  if (Number.isNaN(date.getTime())) {
+    return undefined;
+  }
+  return date;
+}
+
+function formatUtc(date) {
+  return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function historicalWindow(timestamp, minutes) {
+  const date = parseUtcTimestamp(timestamp);
+  if (!date) {
+    return {
+      since: "<incident UTC minus 2 minutes>",
+      until: "<incident UTC plus 2 minutes>",
+      grepPattern: "<YYYY-MM-DD[ T]HH:MM range for incident window>"
+    };
+  }
+  const since = new Date(date.getTime() - minutes * 60 * 1000);
+  const until = new Date(date.getTime() + minutes * 60 * 1000);
+  const yyyyMmDd = date.toISOString().slice(0, 10);
+  const hour = date.toISOString().slice(11, 13);
+  const minute = date.toISOString().slice(14, 16);
+  const minuteInt = Number(minute);
+  const low = Math.max(0, minuteInt - minutes);
+  const high = Math.min(59, minuteInt + minutes);
+  const minuteAlternation = Array.from({ length: high - low + 1 }, (_, index) => String(low + index).padStart(2, "0")).join("|");
+  return {
+    since: formatUtc(since),
+    until: formatUtc(until),
+    grepPattern: `${yyyyMmDd}[ T]${hour}:(${minuteAlternation})`
+  };
+}
+
+class BdsYarnAppHealthCommandPack {
+  constructor(input) {
+    this.cluster = input.cluster;
+    this.driverHost = input.driverHost;
+    this.applicationId = input.applicationId;
+    this.tenant = input.tenant;
+    this.appOwner = input.appOwner;
+    this.logRoot = input.logRoot ?? DEFAULT_LOG_ROOT;
+    this.kerberosPrincipal = input.kerberosPrincipal ?? "workdayadmin";
+    this.kerberosKeytab = input.kerberosKeytab ?? "/etc/hadoop/conf/workdayadmin.keytab";
+    this.nodeHosts = input.nodeHosts ?? [];
+    this.incidentTimestampUtc = input.incidentTimestampUtc;
+    this.historicalWindowMinutes = input.historicalWindowMinutes ?? 2;
+  }
+
+  ssh(command) {
+    return `ssh -o BatchMode=yes -o ConnectTimeout=20 -- ${this.driverHost} ${JSON.stringify(command)}`;
+  }
+
+  kinitPrefix() {
+    return `kinit -kt ${shellQuote(this.kerberosKeytab)} ${shellQuote(this.kerberosPrincipal)}`;
+  }
+
+  sudoWrapperExample(command) {
+    return `mcp__devops-tool__workday_private_cloud_sudo_readonly_command ${JSON.stringify({
+      action: "run",
+      host: this.driverHost,
+      command,
+      humanApprovedSudoRead: true
+    })}`;
+  }
+
+  appPathCandidates() {
+    const candidates = [];
+    if (this.appOwner) {
+      candidates.push(hdfsGlobForKnownOwner({
+        logRoot: this.logRoot,
+        appOwner: this.appOwner,
+        appId: this.applicationId
+      }));
+    }
+    if (this.tenant) {
+      candidates.push(`${this.logRoot}/${this.tenant}/{logs,logs-tfile}/${this.applicationId}`);
+    }
+    candidates.push(`${this.logRoot}/<appOwner>/bucket-logs-tfile/${appBucket(this.applicationId)}/${this.applicationId}`);
+    return Array.from(new Set(candidates));
+  }
+
+  nodeStatusCommands() {
+    const hosts = this.nodeHosts.length ? this.nodeHosts : ["<host-from-aggregated-log-file-name>"];
+    return hosts.map((host) => `timeout 20s yarn node -status ${host}:45454 2>&1 | egrep 'Node-State|Node-Http-Address|Last-Health-Update|Health-Report|Containers|Memory|CPU|Node-Labels|Resource Utilization'`).join("\n");
+  }
+
+  hdfsMatchCommands() {
+    const hosts = this.nodeHosts.length ? this.nodeHosts : ["<host-from-aggregated-log-file-name>"];
+    return hosts.map((host) => `timeout 20s hdfs dfsadmin -report 2>&1 | grep -F -A18 '(${host})' || true`).join("\n");
+  }
+
+  mcpSafeCommandInputs() {
+    const driver = this.driverHost;
+    const appPath = this.appOwner
+      ? hdfsGlobForKnownOwner({ logRoot: this.logRoot, appOwner: this.appOwner, appId: this.applicationId })
+      : undefined;
+    const window = this.historicalWindow();
+    const kinit = `kinit -kt ${this.kerberosKeytab} ${this.kerberosPrincipal}`;
+    const items = [
+      { label: "driver-hostname", input: remoteCommandInput({ host: driver, command: "hostname -f" }) },
+      { label: "driver-utc", input: remoteCommandInput({ host: driver, command: "date -u" }) },
+      { label: "driver-user", input: remoteCommandInput({ host: driver, command: "id -un" }) },
+      { label: "check-yarn", input: remoteCommandInput({ host: driver, command: "command -v yarn" }) },
+      { label: "check-hdfs", input: remoteCommandInput({ host: driver, command: "command -v hdfs" }) },
+      { label: "check-kinit", input: remoteCommandInput({ host: driver, command: "command -v kinit" }) },
+      { label: "kerberos", input: remoteCommandInput({ host: driver, command: kinit }) },
+      { label: "rm-state", input: remoteCommandInput({ host: driver, command: `yarn application -status ${this.applicationId}` }) },
+      { label: "rm-application-summary", input: remoteCommandInput({ host: driver, command: `grep -h 'ApplicationSummary' /var/log/hadoop-yarn/yarn-yarn-resourcemanager-*.log* | grep '${this.applicationId}' | grep 'exitCode: 0' | head -20` }) },
+      {
+        label: "log-info",
+        input: remoteCommandInput({
+          host: driver,
+          command: `yarn logs -applicationId ${this.applicationId}${this.appOwner ? ` -appOwner ${this.appOwner}` : ""} -show_application_log_info | head -300`
+        })
+      },
+      {
+        label: "hdfs-find-log-path",
+        input: remoteCommandInput({
+          host: driver,
+          command: `hdfs dfs -find ${shellQuote(this.logRoot)} -name ${shellQuote(`*${this.applicationId}*`)} | head -300`,
+          timeoutMs: 120_000
+        })
+      },
+      { label: "hdfs-report-summary", input: remoteCommandInput({ host: driver, command: "hdfs dfsadmin -report | head -35" }) },
+    ];
+    if (appPath) {
+      items.push(
+        { label: "list-log-host-files", input: remoteCommandInput({ host: driver, command: `hdfs dfs -ls ${shellQuote(appPath)} | head -300` }) },
+        { label: "size-log-host-files", input: remoteCommandInput({ host: driver, command: `hdfs dfs -du -h ${shellQuote(appPath)} | head -300` }) },
+      );
+    }
+    if (this.nodeHosts.length) {
+      items.push(...this.nodeHosts.flatMap((host) => [
+        {
+          label: `yarn-node-${host}`,
+          input: remoteCommandInput({
+            host: driver,
+            command: `yarn node -status ${host}:45454 | egrep 'Node-State|Node-Http-Address|Last-Health-Update|Health-Report|Containers|Memory|CPU|Node-Labels|Resource Utilization'`
+          })
+        },
+        {
+          label: `hdfs-datanode-${host}`,
+          input: remoteCommandInput({
+            host: driver,
+            command: `hdfs dfsadmin -report | grep -F -A18 '(${host})'`
+          })
+        },
+        {
+          label: `historical-kernel-${host}`,
+          input: remoteCommandInput({
+            host,
+            command: `journalctl -k --since ${shellQuote(window.since)} --until ${shellQuote(window.until)} --no-pager | egrep -i 'error|warn|fail|failed|timeout|timed out|reset|I/O|blk_update_request|medium error|disk|volume|network|hung|blocked|oom|killed|read-only|corrupt|stale|dead|unhealthy' | head -20`
+          })
+        },
+        {
+          label: `historical-yarn-hdfs-${host}`,
+          input: remoteCommandInput({
+            host,
+            command: `grep -hE ${shellQuote(window.grepPattern)} /var/log/hadoop-yarn/yarn-yarn-nodemanager-*.log* /var/log/hadoop-hdfs/hadoop-hdfs-datanode-*.log* | egrep -i 'ERROR|WARN|Exception|timeout|timed out|Lost|UNHEALTHY|unhealthy|failed|Failed|network|Network|Connection|refused|reset|slow|Slow|health|I/O error|corrupt|stale|dead|OutOfMemory|Killed' | egrep -v 'DFSUtil.*duration=0|Scheduling blk_|Deleted BP-|DataNode.clienttrace|PacketResponder:.*terminating' | head -40`
+          })
+        },
+        {
+          label: `historical-long-gc-${host}`,
+          input: remoteCommandInput({
+            host,
+            command: `grep -hE ${shellQuote(`${window.grepPattern}.*Pause`)} /var/log/hadoop-yarn/gc-nodemanager-*.log* /var/log/hadoop-hdfs/gc-datanode-*.log* | egrep '([1-9][0-9]{3,}ms|[0-9]+\\.[0-9]+s)' | head -10`
+          })
+        }
+      ]));
+    }
+    return items;
+  }
+
+  mcpSafeReadiness() {
+    const missing = [];
+    if (!this.appOwner) {
+      missing.push("appOwner is unknown, so list-log-host-files and size-log-host-files are omitted until hdfs-find-log-path or yarn log metadata reveals the owner/path.");
+    }
+    if (!this.nodeHosts.length) {
+      missing.push("nodeHosts are unknown, so yarn-node, hdfs-datanode, and historical host-log commands are omitted until aggregated log filenames reveal the app hosts.");
+    }
+    return {
+      concreteOnly: true,
+      omittedUntilDiscovered: missing,
+      nextStep: missing.length
+        ? "Run only the concrete MCP-safe commands shown, then call bds_yarn_app_health_command_pack again with discovered appOwner and nodeHosts."
+        : "All app-owner and node-host dependent MCP-safe commands are concrete."
+    };
+  }
+
+  historicalWindow() {
+    return historicalWindow(this.incidentTimestampUtc, this.historicalWindowMinutes);
+  }
+
+  historicalHealthCommands() {
+    const hosts = this.nodeHosts.length ? this.nodeHosts : ["<host-from-aggregated-log-file-name>"];
+    const window = this.historicalWindow();
+    const remoteScript = [
+      "set +e",
+      "export LC_ALL=C",
+      "host=$(hostname -f 2>/dev/null || hostname)",
+      "echo \"HOST $host\"",
+      `echo "WINDOW ${window.since} to ${window.until}"`,
+      "echo KERNEL_MATCHES",
+      `journalctl -k --since ${shellQuote(window.since)} --until ${shellQuote(window.until)} --no-pager 2>/dev/null \\`,
+      "  | egrep -i 'error|warn|fail|failed|timeout|timed out|reset|I/O|blk_update_request|medium error|disk|volume|network|hung|blocked|oom|killed|read-only|corrupt|stale|dead|unhealthy' \\",
+      "  | head -20",
+      "echo NM_DN_MATCHES",
+      `PAT=${shellQuote(window.grepPattern)}`,
+      "ERR='ERROR|WARN|Exception|timeout|timed out|Lost|UNHEALTHY|unhealthy|failed|Failed|network|Network|Connection|refused|reset|slow|Slow|health|I/O error|corrupt|stale|dead|OutOfMemory|Killed'",
+      "for f in /var/log/hadoop-yarn/yarn-yarn-nodemanager-*.log* /var/log/hadoop-hdfs/hadoop-hdfs-datanode-*.log*; do",
+      "  [ -f \"$f\" ] || continue",
+      "  case \"$f\" in *.gz) cmd=zgrep ;; *) cmd=grep ;; esac",
+      "  matches=$($cmd -E \"$PAT\" \"$f\" 2>/dev/null | egrep -i \"$ERR\" | egrep -v 'DFSUtil.*duration=0|Scheduling blk_|Deleted BP-|DataNode.clienttrace|PacketResponder:.*terminating' | head -10)",
+      "  if [ -n \"$matches\" ]; then echo \"FILE:$f\"; printf '%s\\n' \"$matches\"; fi",
+      "done",
+      "echo LONG_GC_PAUSES",
+      "for f in /var/log/hadoop-yarn/gc-nodemanager-*.log* /var/log/hadoop-hdfs/gc-datanode-*.log*; do",
+      "  [ -f \"$f\" ] || continue",
+      "  case \"$f\" in *.gz) cmd=zgrep ;; *) cmd=grep ;; esac",
+      "  $cmd -E \"$PAT.*Pause\" \"$f\" 2>/dev/null | awk '{line=$0; dur=$(NF); sub(/ms$/, \"\", dur); if (dur+0 >= 1000) print line}' | head -5 | sed \"s#^#FILE:$f #\"",
+      "done"
+    ].join("\n");
+    return hosts.map((host) => [
+      `echo ===== ${host} =====`,
+      `ssh -o BatchMode=yes -o ConnectTimeout=20 -o ControlMaster=no -- ${host} ${shellQuote(remoteScript)}`
+    ].join("\n")).join("\n\n");
+  }
+
+  commands() {
+    const appPath = this.appOwner
+      ? hdfsGlobForKnownOwner({ logRoot: this.logRoot, appOwner: this.appOwner, appId: this.applicationId })
+      : `<resolved HDFS app log path for ${this.applicationId}>`;
+
+    return [
+      new ReadOnlyStep({
+        id: "01-access-and-identity",
+        purpose: "Confirm the driver host, UTC clock, available Hadoop/YARN commands, and sudo timestamp without changing state.",
+        command: this.ssh("hostname -f; date -u; id -un; sudo -n true >/dev/null 2>&1; echo SUDO_N_STATUS_$?; command -v yarn; command -v hdfs; command -v kinit"),
+        expectedEvidence: "driver host identity, time anchor, current user, sudo availability, yarn/hdfs/kinit paths"
+      }),
+      new ReadOnlyStep({
+        id: "02-kerberos-and-rm-state",
+        purpose: "Initialize Kerberos from the existing keytab and separate RM/Timeline state from filesystem log state.",
+        command: `${this.kinitPrefix()}; timeout 30s yarn application -status ${this.applicationId} 2>&1; echo STATUS_RC:$?`,
+        expectedEvidence: "application state if still in RM/Timeline, or explicit not-found evidence"
+      }),
+      new ReadOnlyStep({
+        id: "02b-rm-application-summary",
+        purpose: "Recover historical RM completion evidence when RM/Timeline no longer retains the app, and support failed Spark app list investigations.",
+        command: `grep -h 'ApplicationSummary' /var/log/hadoop-yarn/yarn-yarn-resourcemanager-*.log* | grep ${shellQuote(this.applicationId)} | grep 'exitCode: 0' | head -20`,
+        expectedEvidence: "ApplicationSummary line with finalStatus, diagnostics, finish time, queue, user, and appMasterHost when the app is no longer available through yarn application -status"
+      }),
+      new ReadOnlyStep({
+        id: "03-log-info-without-full-log",
+        purpose: "Ask YARN for aggregated log metadata before pulling full logs; this avoids hanging on very large driver logs.",
+        command: `${this.kinitPrefix()}; timeout 60s yarn logs -applicationId ${this.applicationId}${this.appOwner ? ` -appOwner ${this.appOwner}` : ""} -show_application_log_info 2>&1 | head -300`,
+        expectedEvidence: "Application State, log aggregation fallback message, app owner hints, container or node log metadata"
+      }),
+      new ReadOnlyStep({
+        id: "04-discover-aggregated-log-path",
+        purpose: "Find the precise HDFS aggregated log path when owner or suffix is unknown; support bucket-logs-tfile/<last4> layout.",
+        command: [
+          `${this.kinitPrefix()};`,
+          `# Candidate paths: ${this.appPathCandidates().join(" ; ")}`,
+          hdfsFindCommand(this.logRoot, this.applicationId)
+        ].join(" "),
+        expectedEvidence: "exact HDFS app log directory, app owner, suffix such as logs-tfile or bucket-logs-tfile, and bucket number"
+      }),
+      new ReadOnlyStep({
+        id: "05-list-log-host-files",
+        purpose: "List host-level aggregated log files and sizes to identify the YARN nodes used by the app and unusually large logs.",
+        command: [
+          `${this.kinitPrefix()};`,
+          `timeout 20s hdfs dfs -ls ${shellQuote(appPath)} 2>&1 | head -300;`,
+          `timeout 20s hdfs dfs -du -h ${shellQuote(appPath)} 2>&1 | head -300`
+        ].join(" "),
+        expectedEvidence: "hostnames from file names, file sizes, replication size, driver log size outliers"
+      }),
+      new ReadOnlyStep({
+        id: "06-yarn-node-health",
+        purpose: "Cross-check every host from aggregated logs against current YARN NodeManager health.",
+        command: `${this.kinitPrefix()}\n${this.nodeStatusCommands()}`,
+        expectedEvidence: "Node-State, Health-Report, Last-Health-Update, resource usage, and container counts for every app host"
+      }),
+      new ReadOnlyStep({
+        id: "07-hdfs-cluster-health",
+        purpose: "Check current HDFS cluster health counters and determine which app hosts are also DataNodes.",
+        command: [
+          `${this.kinitPrefix()}`,
+          "timeout 45s hdfs dfsadmin -report 2>&1 | head -35",
+          this.hdfsMatchCommands()
+        ].join("\n"),
+        expectedEvidence: "live DataNode count, under-replicated blocks, missing blocks, corrupt replicas, and per-host DataNode status where applicable"
+      }),
+      new ReadOnlyStep({
+        id: "08-historical-incident-window",
+        purpose: "Check the exact incident window for kernel, NodeManager, DataNode, disk, network, timeout, unhealthy, and long-GC signals without changing host state.",
+        command: this.historicalHealthCommands(),
+        expectedEvidence: "per-host historical kernel/YARN/HDFS health matches around the incident timestamp, with known noise filtered and failed SSH hosts retried narrowly"
+      })
+    ];
+  }
+
+  toMarkdown() {
+    return [
+      "# BDS YARN App Host Health Read-Only Command Pack",
+      "",
+      this.cluster ? `Cluster: ${this.cluster}` : "",
+      `Driver host: ${this.driverHost}`,
+      `Application ID: ${this.applicationId}`,
+      this.incidentTimestampUtc ? `Incident UTC: ${this.incidentTimestampUtc}` : "",
+      this.tenant ? `Tenant: ${this.tenant}` : "",
+      this.appOwner ? `App owner: ${this.appOwner}` : "",
+      `Log root: ${this.logRoot}`,
+      "",
+      "## Safety Boundary",
+      "",
+      ...SAFETY_RULES.map((rule) => `- ${rule}`),
+      "",
+      "## Credential Handling",
+      "",
+      "- Use Boundary/SSH access to the driver host.",
+      "- Use the existing Kerberos keytab via `kinit -kt`; do not print keytab material.",
+      "- If sudo is needed to become root, pass the saved LDAP token through stdin only.",
+      "",
+      "```bash",
+      this.sudoWrapperExample(`${this.kinitPrefix()}; yarn application -status ${this.applicationId}`),
+      "```",
+      "",
+      "## Read-Only Commands",
+      "",
+      ...this.commands().map((command) => command.toMarkdown()),
+      "",
+      "## MCP-Safe Remote Execution",
+      "",
+      "When using `remote_readonly_command`, run one concrete JSON input at a time from the structured list below. This list intentionally omits commands that still need discovered appOwner or nodeHosts. Do not copy commands from the earlier bash examples into MCP tool calls. Do not combine commands with `;`, `&&`, command substitution, sudo, shell redirection, nested ssh, or local file writes. If one of these read-only commands is denied or unavailable, report that exact evidence gap and stay within this PRISM/YARN/DataNode investigation.",
+      "",
+      `Concrete-only status: ${this.mcpSafeReadiness().nextStep}`,
+      "",
+      "```json",
+      JSON.stringify(this.mcpSafeCommandInputs(), null, 2),
+      "```",
+      "",
+      "Procedure, interpretation, and response shape live in the `bds-yarn-app-health-investigation` skill and runbook."
+    ].filter(Boolean).join("\n");
+  }
+
+  toJson() {
+    return {
+      cluster: this.cluster,
+      driverHost: this.driverHost,
+      applicationId: this.applicationId,
+      tenant: this.tenant,
+      appOwner: this.appOwner,
+      logRoot: this.logRoot,
+      appBucket: appBucket(this.applicationId),
+      incidentTimestampUtc: this.incidentTimestampUtc,
+      historicalWindow: this.historicalWindow(),
+      candidatePaths: this.appPathCandidates(),
+      nodeHosts: this.nodeHosts,
+      safetyBoundary: SAFETY_RULES,
+      historicalNoiseFilters: HISTORICAL_NOISE_FILTERS,
+      mcpSafeReadiness: this.mcpSafeReadiness(),
+      mcpSafeRemoteCommands: this.mcpSafeCommandInputs(),
+      commands: this.commands().map((command) => command.toJson())
+    };
+  }
+}
+
+function buildResponse(input) {
+  const commandPack = new BdsYarnAppHealthCommandPack(input);
+  if (input.format === "json") {
+    return JSON.stringify(commandPack.toJson(), null, 2);
+  }
+  return commandPack.toMarkdown();
+}
+
+export default defineReadOnlyTool({
+  name: "bds_yarn_app_health_command_pack",
+  description: "Generate a atomic-helper, read-only BDS YARN application command pack for app timeout requests, aggregated log host discovery, NodeManager health, and DataNode cross-checks; does not SSH, run YARN, or inspect HDFS.",
+  meta: {
+    permissions: { rule: "ask" },
+    secret_provider: "keychain"
+  },
+  inputSchema: {
+    cluster: clusterSchema.describe("Optional BDS cluster name, for example BDS_ASH_CUST_AZ1."),
+    driverHost: hostSchema.describe("Driver or cluster host used for read-only SSH/YARN/HDFS checks."),
+    applicationId: appIdSchema.describe("YARN application id, for example application_1778917335863_0195."),
+    tenant: tenantSchema.describe("Optional tenant from the request log, for example WD1-PROD.clearskyhealth."),
+    appOwner: ownerSchema.describe("Optional YARN app owner if already known, for example wd1-prod_prism."),
+    logRoot: pathSchema.describe("YARN aggregated log root."),
+    nodeHosts: hostListSchema.describe("Optional app host list discovered from aggregated log filenames."),
+    incidentTimestampUtc: utcTimestampSchema.describe("Optional incident timestamp in UTC, for example 2026-05-22 02:46:56.993 UTC."),
+    historicalWindowMinutes: minuteWindowSchema.describe("Minutes before and after incidentTimestampUtc to inspect in historical host logs."),
+    kerberosPrincipal: principalSchema,
+    kerberosKeytab: keytabSchema,
+    format: z.enum(["markdown", "json"]).default("markdown")
+  },
+  annotations: { openWorldHint: true },
+  async handler(input) {
+    try {
+      return ok(buildResponse(input));
+    } catch (error) {
+      return fail(error);
+    }
+  }
+});
+
+export const __test = { appBucket, hdfsGlobForKnownOwner, hdfsFindCommand, historicalWindow, BdsYarnAppHealthCommandPack };

package/tools/bds_yarn_nodemanager_log_read.mjs

@@ -0,0 +1,23 @@
+export const description = "Read YARN NodeManager logs from a private-cloud NM/DataNode host through the approved Boundary sudo read tool.";
+
+import { createPrivateCloudLogReadTool, globPrivateLogSpec } from "../src/bds-atomic-log-tools.mjs";
+
+const spec = globPrivateLogSpec({
+  toolName: "bds_yarn_nodemanager_log_read",
+  description: "Read YARN NodeManager logs from a private-cloud NM/DataNode host through the approved Boundary sudo read tool.",
+  glob: "/var/log/hadoop-yarn/yarn-yarn-nodemanager-*.log"
+});
+
+export const __test = spec;
+
+const sharedTool = createPrivateCloudLogReadTool(spec);
+
+export default {
+  name: sharedTool.name,
+  description,
+  inputSchema: sharedTool.inputSchema,
+  meta: sharedTool.meta,
+  annotations: sharedTool.annotations,
+  invoke: sharedTool.invoke,
+  handler: sharedTool.handler
+};

package/tools/bds_yarn_resourcemanager_log_read.mjs

@@ -0,0 +1,23 @@
+export const description = "Read YARN ResourceManager logs from a private-cloud RM host through the approved Boundary sudo read tool.";
+
+import { createPrivateCloudLogReadTool, globPrivateLogSpec } from "../src/bds-atomic-log-tools.mjs";
+
+const spec = globPrivateLogSpec({
+  toolName: "bds_yarn_resourcemanager_log_read",
+  description: "Read YARN ResourceManager logs from a private-cloud RM host through the approved Boundary sudo read tool.",
+  glob: "/var/log/hadoop-yarn/yarn-yarn-resourcemanager-*.log"
+});
+
+export const __test = spec;
+
+const sharedTool = createPrivateCloudLogReadTool(spec);
+
+export default {
+  name: sharedTool.name,
+  description,
+  inputSchema: sharedTool.inputSchema,
+  meta: sharedTool.meta,
+  annotations: sharedTool.annotations,
+  invoke: sharedTool.invoke,
+  handler: sharedTool.handler
+};

package/tools/bds_zookeeper_log_read.mjs

@@ -0,0 +1,23 @@
+export const description = "Read ZooKeeper server logs from a private-cloud ZooKeeper host through the approved Boundary sudo read tool.";
+
+import { createPrivateCloudLogReadTool, globPrivateLogSpec } from "../src/bds-atomic-log-tools.mjs";
+
+const spec = globPrivateLogSpec({
+  toolName: "bds_zookeeper_log_read",
+  description: "Read ZooKeeper server logs from a private-cloud ZooKeeper host through the approved Boundary sudo read tool.",
+  glob: "/var/log/zookeeper/zookeeper-zookeeper-server-*.log"
+});
+
+export const __test = spec;
+
+const sharedTool = createPrivateCloudLogReadTool(spec);
+
+export default {
+  name: sharedTool.name,
+  description,
+  inputSchema: sharedTool.inputSchema,
+  meta: sharedTool.meta,
+  annotations: sharedTool.annotations,
+  invoke: sharedTool.invoke,
+  handler: sharedTool.handler
+};