ralph-hero-mcp-server 2.5.142 → 2.5.168

package/dist/index.js

@@ -31,7 +31,9 @@ import { registerDecomposeTools } from "./tools/decompose-tools.js";
 import { registerViewTools } from "./tools/view-tools.js";
 import { registerPlanGraphTools } from "./tools/plan-graph-tools.js";
 import { registerActivityTools } from "./tools/activity-tools.js";
+import { registerDelegationTools } from "./tools/delegation-tools.js";
 import { registerTrendsTools } from "./tools/trends-tools.js";
+import { registerSreTools } from "./tools/sre-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -445,8 +447,12 @@ async function main() {
     registerPlanGraphTools(server, client);
     // Activity log reader (recent_activity tool — pure filesystem, no GitHub client)
     registerActivityTools(server);
+    // Delegation telemetry reader (delegation_stats tool — pure filesystem, no GitHub client)
+    registerDelegationTools(server);
     // Trends tools (capture_snapshot — JSONL persistence under ~/.ralph-hero/snapshots/)
     registerTrendsTools(server, client, fieldCache);
+    // SRE operation tools (kubectl autoremediation — typed argv, no-shell invariant)
+    registerSreTools(server, client, fieldCache);
     // Debug tools (only when RALPH_DEBUG=true)
     if (process.env.RALPH_DEBUG === 'true') {
         registerDebugTools(server, client);

package/dist/lib/delegation-log.js

@@ -0,0 +1,199 @@
+/**
+ * Pure read library for the local ralph-delegate JSONL audit log.
+ *
+ * The log lives at `~/.ralph-hero/delegate.log` (overridable via
+ * `RALPH_DELEGATE_LOG_PATH`). One JSON object per line, append-only,
+ * written by `plugin/ralph-hero/scripts/ralph-delegate.sh`. This library
+ * only reads — it never writes.
+ *
+ * Schema versioning: F1 (issue #1185) does NOT emit an explicit
+ * `schemaVersion` field on each line. F5 treats lines containing the
+ * required fields `{ts, task, status, ms}` as **implicit v1**. A future
+ * issue MAY add an explicit `schemaVersion >= 2` — when that happens, the
+ * shape-check should be expanded to honor it. TODO: revisit when the
+ * producer side emits `schemaVersion`.
+ *
+ * Determinism: pure functions. Filesystem reads are the only side effect.
+ * Missing log file resolves to a zero-state result with no throw, matching
+ * the activity.ts precedent (the steady state for opt-out users).
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Test hook + default path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Optional override used only by tests. Production code never sets this.
+ * Mirrors `__setSnapshotRoot` in `snapshots.ts`.
+ */
+let delegateLogPathOverride = null;
+/** Test hook: override the default log path. Pass `null` to restore. */
+export function __setDelegateLogPath(path) {
+    delegateLogPathOverride = path;
+}
+/**
+ * Resolve the default log path: env var override, then `~/.ralph-hero/delegate.log`.
+ * Expands a leading `~/` (mirrors `ralph-delegate.sh:208-211`).
+ */
+export function defaultDelegationLogPath() {
+    if (delegateLogPathOverride !== null)
+        return delegateLogPathOverride;
+    const fromEnv = process.env.RALPH_DELEGATE_LOG_PATH;
+    if (fromEnv && fromEnv.length > 0) {
+        return expandHome(fromEnv);
+    }
+    return path.join(os.homedir(), ".ralph-hero", "delegate.log");
+}
+function expandHome(p) {
+    if (p.startsWith("~/")) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+// ---------------------------------------------------------------------------
+// Reader
+// ---------------------------------------------------------------------------
+/**
+ * Read the delegation audit log. Returns a zero-state result with
+ * `fileExists: false` when the file is missing — never throws on ENOENT.
+ * Lines that fail JSON.parse OR lack required fields are skipped and
+ * counted in `skippedLines`; each skip emits a `console.warn` with a
+ * truncated prefix of the offending line.
+ */
+export async function readDelegationLog(config) {
+    const logPath = config.logPath;
+    let content;
+    try {
+        content = await fs.readFile(logPath, "utf8");
+    }
+    catch (e) {
+        if (e &&
+            typeof e === "object" &&
+            "code" in e &&
+            e.code === "ENOENT") {
+            return { events: [], skippedLines: 0, fileExists: false, logPath };
+        }
+        throw e;
+    }
+    const events = [];
+    let skipped = 0;
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            skipped++;
+            console.warn(`[delegation-log] Skipping malformed line in ${logPath}: ${line.slice(0, 80)}`);
+            continue;
+        }
+        if (!isDelegationEventShape(parsed)) {
+            skipped++;
+            console.warn(`[delegation-log] Skipping line with missing required fields in ${logPath}: ${line.slice(0, 80)}`);
+            continue;
+        }
+        events.push(parsed);
+    }
+    return { events, skippedLines: skipped, fileExists: true, logPath };
+}
+/**
+ * Implicit-v1 shape check: presence of `{ts, task, status, ms}` with
+ * correct primitive types. A future explicit `schemaVersion >= 2` may
+ * extend this gate.
+ */
+function isDelegationEventShape(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    return (typeof o.ts === "string" &&
+        typeof o.task === "string" &&
+        typeof o.status === "string" &&
+        typeof o.ms === "number");
+}
+// ---------------------------------------------------------------------------
+// Aggregator
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate parsed events into per-task + totals. Pure function — does
+ * no I/O. Percentiles use the nearest-rank method against successful
+ * (status=ok) calls only.
+ */
+export function aggregateDelegationStats(events) {
+    const byTask = {};
+    const okMsByTask = {};
+    let totalCalls = 0;
+    let totalFallbacks = 0;
+    let totalBytesIn = 0;
+    let totalBytesOut = 0;
+    for (const ev of events) {
+        const task = ev.task;
+        if (!byTask[task]) {
+            byTask[task] = {
+                calls: 0,
+                fallbacks: 0,
+                p50Ms: null,
+                p99Ms: null,
+                bytesIn: 0,
+                bytesOut: 0,
+                tokens: null,
+            };
+            okMsByTask[task] = [];
+        }
+        byTask[task].calls += 1;
+        totalCalls += 1;
+        if (isFallbackStatus(ev.status)) {
+            byTask[task].fallbacks += 1;
+            totalFallbacks += 1;
+        }
+        const bIn = typeof ev.bytes_in === "number" ? ev.bytes_in : 0;
+        const bOut = typeof ev.bytes_out === "number" ? ev.bytes_out : 0;
+        byTask[task].bytesIn += bIn;
+        byTask[task].bytesOut += bOut;
+        totalBytesIn += bIn;
+        totalBytesOut += bOut;
+        if (ev.status === "ok") {
+            okMsByTask[task].push(ev.ms);
+        }
+    }
+    // Compute percentiles
+    for (const task of Object.keys(byTask)) {
+        const samples = okMsByTask[task];
+        byTask[task].p50Ms = percentile(samples, 0.5);
+        byTask[task].p99Ms = percentile(samples, 0.99);
+    }
+    return {
+        totals: {
+            calls: totalCalls,
+            fallbacks: totalFallbacks,
+            bytesIn: totalBytesIn,
+            bytesOut: totalBytesOut,
+        },
+        byTask,
+    };
+}
+/**
+ * A fallback is any non-`ok`, non-`dry_run` status: timeout, unreachable,
+ * parse_error, http_*. `dry_run` is operator-driven and not a real
+ * delegation failure, so it does not count.
+ */
+function isFallbackStatus(status) {
+    return status !== "ok" && status !== "dry_run";
+}
+/**
+ * Nearest-rank percentile: `sorted[ceil(q * n) - 1]`. Returns `null`
+ * when the sample is empty.
+ */
+function percentile(samples, q) {
+    if (samples.length === 0)
+        return null;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const rank = Math.ceil(q * sorted.length);
+    // Guard the edge case q=0 (would index -1)
+    const idx = Math.max(0, rank - 1);
+    return sorted[idx];
+}
+//# sourceMappingURL=delegation-log.js.map

package/dist/lib/kubectl-exec.js

@@ -0,0 +1,70 @@
+/**
+ * Shared kubectl execution helper for all SRE operation tools.
+ *
+ * INVARIANT: This module NEVER invokes a shell. All kubectl calls go through
+ * `child_process.execFile` with `shell: false` (the execFile default), which
+ * passes argv directly to execve(2). String-interpolated shell commands and
+ * `exec()` are explicitly forbidden here.
+ *
+ * The {@link FORBIDDEN_FLAGS} list provides a defense-in-depth check on top of
+ * the typed Zod schemas in sre-tools.ts. The typed schemas should already make
+ * these flags unreachable, but the helper enforces a hard floor so a future
+ * regression (e.g., a new typed param that happens to produce a forbidden flag)
+ * is caught at the exec layer, not silently allowed.
+ */
+import { execFile as _execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(_execFile);
+/**
+ * Flags that are unconditionally forbidden in kubectl argv.
+ *
+ * These represent destructive or resource-exhausting operations that the
+ * sre-fixit agent must never perform. They are defense-in-depth: the typed
+ * Zod schemas in sre-tools.ts make them structurally unreachable, but this
+ * list catches future regressions where a new typed param happens to produce
+ * one of these strings.
+ */
+export const FORBIDDEN_FLAGS = [
+    "--force",
+    "--cascade=foreground",
+    "--grace-period=0",
+    "--delete-emptydir-data",
+];
+/**
+ * Execute kubectl with the given argv array.
+ *
+ * Uses `child_process.execFile` (shell: false by default) so the argv is
+ * passed directly to execve(2) — no shell interpretation, no metacharacter
+ * expansion, no glob expansion.
+ *
+ * @param args - Typed argv array (e.g. `["scale", "--namespace", "default", ...]`).
+ *               Never accepts a string command.
+ * @throws {Error} If any element of `args` matches a {@link FORBIDDEN_FLAGS} entry.
+ * @returns A typed result with `stdout`, `stderr`, and `exitCode`.
+ */
+export async function runKubectl(args) {
+    // Defense-in-depth: reject any argv element that matches a forbidden flag.
+    for (const arg of args) {
+        if (FORBIDDEN_FLAGS.includes(arg)) {
+            throw new Error(`kubectl argv contains forbidden flag: ${arg}. ` +
+                `Forbidden flags: ${FORBIDDEN_FLAGS.join(", ")}`);
+        }
+    }
+    try {
+        const { stdout, stderr } = await execFileAsync("kubectl", args, {
+            shell: false,
+        });
+        return { stdout, stderr, exitCode: 0 };
+    }
+    catch (err) {
+        // execFile rejects when the process exits with a non-zero code.
+        // The error object carries stdout/stderr from the failed run.
+        const e = err;
+        return {
+            stdout: e.stdout ?? "",
+            stderr: e.stderr ?? "",
+            exitCode: typeof e.code === "number" ? e.code : 1,
+        };
+    }
+}
+//# sourceMappingURL=kubectl-exec.js.map

package/dist/tools/delegation-tools.js

@@ -0,0 +1,44 @@
+/**
+ * Registers the `ralph_hero__delegation_stats` MCP tool. Pure read-only
+ * surface over the JSONL audit log written by `ralph-delegate.sh` (F1).
+ *
+ * Follows the same registration convention as `activity-tools.ts`: no
+ * GitHub client argument, defaults pulled from env var with a homedir
+ * fallback, returns `toolSuccess` on missing-file (zero-state) so callers
+ * can render a dashboard without an error path.
+ */
+import { z } from "zod";
+import { readDelegationLog, aggregateDelegationStats, defaultDelegationLogPath, } from "../lib/delegation-log.js";
+import { toolSuccess, toolError } from "../types.js";
+const TOKENS_REASON = "F1 audit-log does not capture token usage; bytes used as a proxy";
+export function registerDelegationTools(server) {
+    server.tool("ralph_hero__delegation_stats", "Read-only telemetry over the local ralph-delegate JSONL audit log. Returns per-task call counts, fallback counts (non-ok/non-dry_run), p50/p99 latency from successful calls, and bytes_in/bytes_out aggregates. Reads RALPH_DELEGATE_LOG_PATH (default ~/.ralph-hero/delegate.log). Missing log file returns a zero-state result, never errors.", {
+        logPath: z
+            .string()
+            .optional()
+            .describe("Optional override for the JSONL log path. Defaults to RALPH_DELEGATE_LOG_PATH or ~/.ralph-hero/delegate.log."),
+    }, async (params) => {
+        try {
+            const resolvedPath = params.logPath ?? defaultDelegationLogPath();
+            const read = await readDelegationLog({ logPath: resolvedPath });
+            const stats = aggregateDelegationStats(read.events);
+            return toolSuccess({
+                logPath: read.logPath,
+                fileExists: read.fileExists,
+                totals: {
+                    calls: stats.totals.calls,
+                    fallbacks: stats.totals.fallbacks,
+                    bytesIn: stats.totals.bytesIn,
+                    bytesOut: stats.totals.bytesOut,
+                    skippedLines: read.skippedLines,
+                },
+                byTask: stats.byTask,
+                tokensReason: TOKENS_REASON,
+            });
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=delegation-tools.js.map

package/dist/tools/sre-tools.js

@@ -0,0 +1,334 @@
+/**
+ * SRE operation tools for kubectl autoremediation.
+ *
+ * This module registers the `ralph_hero__sre__*` family of typed MCP tools.
+ * Each tool accepts explicit, narrowly-typed parameters and delegates to the
+ * shared {@link runKubectl} helper from `../lib/kubectl-exec.ts`.
+ *
+ * INVARIANT (no-shell): All kubectl invocations go through `runKubectl`, which
+ * uses `child_process.execFile` with `shell: false`. There are NO string-
+ * interpolated shell commands, NO `exec()` calls, and NO `Bash` tool usage in
+ * this module or the agent that consumes it. Argv is always a plain array
+ * literal — never built via template strings, string concat, or user-controlled
+ * flag pass-through.
+ *
+ * Phases 2-5 of the GH-1285 plan add the four operation tool registrations
+ * (sre__scale, sre__rollout_restart, sre__delete_pod, sre__drain) inside
+ * `registerSreTools`. Phase 1 (GH-1287) establishes the module skeleton and
+ * wires the registration call in index.ts.
+ */
+import { z } from "zod";
+import { runKubectl } from "../lib/kubectl-exec.js";
+import { toolSuccess, toolError } from "../types.js";
+// ---------------------------------------------------------------------------
+// Shared Zod field schemas
+// ---------------------------------------------------------------------------
+/**
+ * RFC 1123 label regex for Kubernetes namespace and deployment names.
+ * Intentionally rejects shell metacharacters, slashes, newlines, and empty
+ * strings as a single Zod check.
+ */
+const k8sLabelSchema = z.string().min(1).regex(/^[a-z0-9-]+$/);
+/**
+ * Bounded replica count. Ceiling is 50 — configurable in a follow-up; the
+ * explicit ceiling prevents runaway scale-out from an LLM miscalculation.
+ */
+export const REPLICA_CEILING = 50;
+const replicasSchema = z.number().int().min(0).max(REPLICA_CEILING);
+// ---------------------------------------------------------------------------
+// sre__scale schemas
+// ---------------------------------------------------------------------------
+/**
+ * Raw Zod shape for the sre__scale tool.
+ * Passed to `server.tool()` which expects a `ZodRawShape` (plain object of
+ * Zod field schemas).
+ */
+const sreScaleShape = {
+    namespace: k8sLabelSchema.describe("Kubernetes namespace (RFC 1123 label: lowercase alphanumeric and hyphens only)."),
+    deployment: k8sLabelSchema.describe("Deployment name (RFC 1123 label: lowercase alphanumeric and hyphens only)."),
+    replicas: replicasSchema.describe(`Target replica count (integer, 0–${REPLICA_CEILING}).`),
+};
+/**
+ * Strict Zod object schema for sre__scale parameters.
+ *
+ * Exported so adversarial-input tests (sre-tools.test.ts) can call
+ * `.safeParse()` directly. `.strict()` ensures unknown keys are rejected —
+ * any attempt to pass extra fields (e.g., a `flags` bypass) is caught at
+ * the schema level.
+ */
+export const sreScaleSchema = z.object(sreScaleShape).strict();
+/**
+ * Build the kubectl argv array for a scale operation.
+ *
+ * Exported for unit-testing the argv shape independently of the MCP server.
+ * The argv is a plain array literal — no string interpolation, no concat.
+ *
+ * @param namespace  - Validated Kubernetes namespace.
+ * @param deployment - Validated deployment name.
+ * @param replicas   - Validated replica count.
+ */
+export function buildScaleArgv(namespace, deployment, replicas) {
+    return [
+        "scale",
+        "--namespace",
+        namespace,
+        "deployment",
+        deployment,
+        "--replicas",
+        String(replicas),
+    ];
+}
+// ---------------------------------------------------------------------------
+// sre__rollout_restart schemas  (Phase 3 / GH-1289)
+// ---------------------------------------------------------------------------
+/**
+ * Raw Zod shape for the sre__rollout_restart tool.
+ */
+const sreRolloutRestartShape = {
+    namespace: k8sLabelSchema.describe("Kubernetes namespace (RFC 1123 label: lowercase alphanumeric and hyphens only)."),
+    deployment: k8sLabelSchema.describe("Deployment name (RFC 1123 label: lowercase alphanumeric and hyphens only)."),
+};
+/**
+ * Strict Zod object schema for sre__rollout_restart parameters.
+ *
+ * Exported so adversarial-input tests (sre-tools.test.ts) can call
+ * `.safeParse()` directly. `.strict()` ensures unknown keys are rejected.
+ */
+export const sreRolloutRestartSchema = z.object(sreRolloutRestartShape).strict();
+/**
+ * Build the kubectl argv array for a rollout restart operation.
+ *
+ * Exported for unit-testing the argv shape independently of the MCP server.
+ *
+ * NOTE — deliberate template-literal exception: This is the only argv builder
+ * in the sre__* family that uses a template literal. The `deployment/<name>`
+ * form is specific to `kubectl rollout restart`'s resource-qualified argument
+ * syntax. The interpolation is safe by construction: the `deployment` Zod
+ * schema (`/^[a-z0-9-]+$/`) forbids `/`, newlines, and shell metacharacters —
+ * the only characters that could escape the literal prefix. Do NOT generalise
+ * this pattern to other phases; phases 2, 4, and 5 keep plain array literals.
+ *
+ * @param namespace  - Validated Kubernetes namespace.
+ * @param deployment - Validated deployment name.
+ */
+export function buildRolloutRestartArgv(namespace, deployment) {
+    return [
+        "rollout",
+        "restart",
+        "--namespace",
+        namespace,
+        `deployment/${deployment}`,
+    ];
+}
+// ---------------------------------------------------------------------------
+// sre__delete_pod schemas  (Phase 4 / GH-1290)
+// ---------------------------------------------------------------------------
+/**
+ * Raw Zod shape for the sre__delete_pod tool.
+ *
+ * The schema has exactly two fields — `namespace` and `pod`. There is no
+ * label-selector field, no `--force` field, and no `--grace-period` field.
+ * The absence of these fields is the primary typed-surface guarantee: there is
+ * no way to express bulk deletion, forced deletion, or grace-period override
+ * through this schema. `.strict()` rejects any extra keys the caller might
+ * try to pass.
+ */
+const sreDeletePodShape = {
+    namespace: k8sLabelSchema.describe("Kubernetes namespace (RFC 1123 label: lowercase alphanumeric and hyphens only)."),
+    pod: k8sLabelSchema.describe("Pod name to delete (RFC 1123 label: lowercase alphanumeric and hyphens only). " +
+        "Single pod only — no label selector, no wildcard."),
+};
+/**
+ * Strict Zod object schema for sre__delete_pod parameters.
+ *
+ * Exported so adversarial-input tests (sre-tools.test.ts) can call
+ * `.safeParse()` directly, including the `.strict()` no-label-selector
+ * assertion. `.strict()` ensures unknown keys (e.g., `selector: "app=foo"`)
+ * are rejected at the schema level.
+ */
+export const sreDeletePodSchema = z.object(sreDeletePodShape).strict();
+/**
+ * Build the kubectl argv array for a delete-pod operation.
+ *
+ * Exported for unit-testing the argv shape independently of the MCP server.
+ * The argv is a plain array literal — no string interpolation, no concat.
+ *
+ * @param namespace - Validated Kubernetes namespace.
+ * @param pod       - Validated pod name (single pod, no label selector).
+ */
+export function buildDeletePodArgv(namespace, pod) {
+    return ["delete", "pod", "--namespace", namespace, pod];
+}
+// ---------------------------------------------------------------------------
+// sre__drain schemas  (Phase 5 / GH-1291)
+// ---------------------------------------------------------------------------
+/**
+ * Node name regex — slightly looser than the RFC 1123 label regex because
+ * Kubernetes node names can be in FQDN form (e.g., "node-1.us-east-1.example.com").
+ * The dot (`.`) is the only addition over the namespace/deployment regex.
+ * Intentionally rejects shell metacharacters, slashes, newlines, and empty
+ * strings as a single Zod check.
+ */
+const k8sNodeNameSchema = z.string().min(1).regex(/^[a-z0-9.-]+$/);
+/**
+ * Bounded grace period in seconds. Minimum is 1 — gracePeriodSeconds=0 is
+ * equivalent to --force (immediate kill) and is explicitly forbidden by the
+ * plan's Shared Constraint #3.  Maximum is 3600 (one hour).
+ */
+const gracePeriodSecondsSchema = z.number().int().min(1).max(3600);
+/**
+ * Bounded timeout in seconds. Minimum is 1. Maximum is 3600 (one hour).
+ */
+const timeoutSecondsSchema = z.number().int().min(1).max(3600);
+/**
+ * Raw Zod shape for the sre__drain tool.
+ *
+ * `--namespace` is intentionally absent: `kubectl drain` targets a node, which
+ * is a cluster-scoped resource. Do not add a namespace field — its absence is
+ * correct per the plan's Phase 5 note.
+ *
+ * `--ignore-daemonsets` is hard-coded into argv by the builder; it is NOT a
+ * user-controllable parameter. `--force` and `--delete-emptydir-data` are
+ * structurally unreachable through this schema.
+ */
+const sreDrainShape = {
+    node: k8sNodeNameSchema.describe("Node name to drain (RFC 1123 / FQDN form: lowercase alphanumeric, hyphens, and dots only)."),
+    gracePeriodSeconds: gracePeriodSecondsSchema.optional().describe("Grace period for evicting pods in seconds (integer, 1–3600). " +
+        "Omit to use the pod's default. " +
+        "0 is explicitly forbidden (equivalent to --force)."),
+    timeoutSeconds: timeoutSecondsSchema.optional().describe("Timeout for the drain operation in seconds (integer, 1–3600). " +
+        "Omit to use kubectl's default."),
+};
+/**
+ * Strict Zod object schema for sre__drain parameters.
+ *
+ * Exported so adversarial-input tests (sre-tools.test.ts) can call
+ * `.safeParse()` directly. `.strict()` ensures unknown keys are rejected —
+ * any attempt to pass extra fields (e.g., a `force` bypass) is caught at
+ * the schema level.
+ */
+export const sreDrainSchema = z.object(sreDrainShape).strict();
+/**
+ * Build the kubectl argv array for a drain operation.
+ *
+ * Exported for unit-testing the argv shape independently of the MCP server.
+ * The argv is a plain array literal — no string interpolation, no concat
+ * (drain follows the same plain-array-literal pattern as phases 2 and 4).
+ *
+ * INVARIANTS (enforced by construction):
+ *   - `--ignore-daemonsets` is always present (hard-coded, not user-controlled).
+ *   - `--force` is never present (no schema field; helper also rejects it).
+ *   - `--delete-emptydir-data` is never present (no schema field).
+ *   - `--grace-period=0` is never present (gracePeriodSeconds min is 1 via Zod).
+ *
+ * @param node               - Validated node name.
+ * @param gracePeriodSeconds - Optional validated grace period (seconds, >= 1).
+ * @param timeoutSeconds     - Optional validated timeout (seconds, >= 1).
+ */
+export function buildDrainArgv(node, gracePeriodSeconds, timeoutSeconds) {
+    const argv = ["drain", node, "--ignore-daemonsets"];
+    if (gracePeriodSeconds !== undefined) {
+        argv.push("--grace-period", String(gracePeriodSeconds));
+    }
+    if (timeoutSeconds !== undefined) {
+        argv.push("--timeout", `${timeoutSeconds}s`);
+    }
+    return argv;
+}
+// ---------------------------------------------------------------------------
+/**
+ * Register all SRE operation tools on the MCP server.
+ *
+ * The `client` and `fieldCache` parameters are accepted for API consistency
+ * with other `register*Tools` functions. They are unused in Phase 1 (scaffold
+ * only); Phases 2-5 may use `client` for issue context lookups if needed.
+ *
+ * @param server     - The MCP server instance to register tools on.
+ * @param client     - GitHub client (reserved for future phases).
+ * @param fieldCache - Field option cache (reserved for future phases).
+ */
+export function registerSreTools(server, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_client, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_fieldCache) {
+    // -------------------------------------------------------------------------
+    // ralph_hero__sre__scale  (Phase 2 / GH-1288)
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__sre__scale", "Scale a Kubernetes deployment to a specified replica count. " +
+        "Typed parameters only — no shell, no flag pass-through. " +
+        `Replica ceiling: ${REPLICA_CEILING}.`, sreScaleShape, async ({ namespace, deployment, replicas }) => {
+        const argv = buildScaleArgv(namespace, deployment, replicas);
+        try {
+            const result = await runKubectl(argv);
+            if (result.exitCode !== 0) {
+                return toolError(`kubectl scale failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+            }
+            return toolSuccess(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return toolError(`kubectl scale failed: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__sre__rollout_restart  (Phase 3 / GH-1289)
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__sre__rollout_restart", "Trigger a rolling restart of a Kubernetes deployment. " +
+        "Typed parameters only — no shell, no flag pass-through. " +
+        "Equivalent to: kubectl rollout restart deployment/<name> -n <namespace>.", sreRolloutRestartShape, async ({ namespace, deployment }) => {
+        const argv = buildRolloutRestartArgv(namespace, deployment);
+        try {
+            const result = await runKubectl(argv);
+            if (result.exitCode !== 0) {
+                return toolError(`kubectl rollout restart failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+            }
+            return toolSuccess(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return toolError(`kubectl rollout restart failed: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__sre__delete_pod  (Phase 4 / GH-1290)
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__sre__delete_pod", "Delete a single named pod in a Kubernetes namespace. " +
+        "Single pod by name only — no label selector, no --force, no --grace-period=0. " +
+        "Typed parameters only — no shell, no flag pass-through.", sreDeletePodShape, async ({ namespace, pod }) => {
+        const argv = buildDeletePodArgv(namespace, pod);
+        try {
+            const result = await runKubectl(argv);
+            if (result.exitCode !== 0) {
+                return toolError(`kubectl delete pod failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+            }
+            return toolSuccess(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return toolError(`kubectl delete pod failed: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__sre__drain  (Phase 5 / GH-1291)
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__sre__drain", "Drain a Kubernetes node by evicting all non-daemonset pods. " +
+        "--ignore-daemonsets is hard-coded on (always present). " +
+        "--force, --delete-emptydir-data, and --grace-period=0 are structurally unreachable. " +
+        "Cluster-scoped operation — no --namespace flag. " +
+        "Typed parameters only — no shell, no flag pass-through.", sreDrainShape, async ({ node, gracePeriodSeconds, timeoutSeconds }) => {
+        const argv = buildDrainArgv(node, gracePeriodSeconds, timeoutSeconds);
+        try {
+            const result = await runKubectl(argv);
+            if (result.exitCode !== 0) {
+                return toolError(`kubectl drain failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+            }
+            return toolSuccess(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return toolError(`kubectl drain failed: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=sre-tools.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.142",
+  "version": "2.5.168",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",