@ricsam/r5dctl 0.0.49 → 0.0.50

package/README.md

@@ -79,12 +79,18 @@ r5dctl ps list
 r5dctl -p <project> -b <branch> ps list --worker <label>
 r5dctl -s <session-id> ps list --json
 r5dctl ps stop <run-id>
+
+r5dctl k8s usage
+r5dctl k8s usage --namespace default --workload api --container server
+r5dctl k8s usage --workload default/api --window 24h --json
 ```
 
 `shell` connects to the same live worker PTY as the web Shell tab. Without `-c` it attaches the local terminal interactively. With `-c`/`--command`, it runs the supplied shell expression, streams combined PTY output, and exits with the remote command's status. Because command output uses a PTY, stdout and stderr are combined and programs may emit colors or other terminal control sequences.
 
 `ps list` shows active long-running commands managed by r5d. It does not expose the worker host's general OS process table or interactive PTYs. Global project, branch, and session options filter the list, while `--worker` selects a worker label. `ps stop` sends `SIGTERM` to the selected run. Inside an r5d-provided worker shell, the temporary credential can only list and stop runs on that shell's worker.
 
+`k8s usage` shows current and 24-hour CPU and memory usage for every workload container in your managed vCluster. Filter with `--namespace`, `--workload`, or `--container`; a workload may be identified by name, `namespace/name`, or Kubernetes UID. Human-readable output summarizes the 24-hour minimum and maximum across replicas, while global `--json` includes the complete five-minute history envelope and per-pod series. The only currently supported `--window` value is `24h`.
+
 `get envs` reports names and whether values are set, but never prints the values. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
 
 Conversation output is human-readable by default and excludes both the system prompt and tool definitions. `--raw` keeps the transcript layout but renders structured message and tool parts as JSON, `--tools` includes the provider-shaped tool definitions, and `--system` includes system prompt messages. The global `--json` flag remains separate and prints the complete API response envelope.

package/dist/cjs/cli.cjs

@@ -28,6 +28,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var cli_exports = {};
 __export(cli_exports, {
+  collectK8sUsage: () => collectK8sUsage,
+  formatK8sCpu: () => formatK8sCpu,
+  formatK8sMemory: () => formatK8sMemory,
   formatProcessAge: () => formatProcessAge,
   getCliHelpText: () => getCliHelpText,
   getR5dctlVersion: () => getR5dctlVersion,
@@ -38,6 +41,7 @@ __export(cli_exports, {
   parseEnvFlags: () => parseEnvFlags,
   parseEnvRequestResponseArgs: () => parseEnvRequestResponseArgs,
   parseGlobalArgs: () => parseGlobalArgs,
+  parseK8sUsageArgs: () => parseK8sUsageArgs,
   parsePromptArgs: () => parsePromptArgs,
   parsePsHistoryArgs: () => parsePsHistoryArgs,
   parsePsListArgs: () => parsePsListArgs,
@@ -48,6 +52,7 @@ __export(cli_exports, {
   renderConversationOverviewResponse: () => renderConversationOverviewResponse,
   renderConversationResponse: () => renderConversationResponse,
   renderConversationWorkResponse: () => renderConversationWorkResponse,
+  renderK8sUsageReport: () => renderK8sUsageReport,
   renderProcessHistory: () => renderProcessHistory,
   renderProcessInspection: () => renderProcessInspection,
   renderProcessList: () => renderProcessList,
@@ -126,6 +131,13 @@ const PS_HELP_TEXT = [
   "Use -p/--project, -b/--branch, or -s/--session to filter list and history.",
   ""
 ].join("\n");
+const K8S_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window=24h]",
+  "",
+  "Show current and 24-hour CPU and memory usage for managed-vCluster workload containers.",
+  ""
+].join("\n");
 const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth status", description: "Show the current authenticated user and credential source." },
   { section: "auth", usage: "auth logout", description: "Revoke the current credential and clear saved auth." },
@@ -221,6 +233,11 @@ const SHARED_HELP_ENTRIES = [
     usage: "-s <session-id> answer-env-request [-e KEY=value] [--context <text>]",
     description: "Answer a pending environment variable request with values, context, or both."
   },
+  {
+    section: "kubernetes",
+    usage: "k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window=24h]",
+    description: "Show current and 24-hour CPU and memory usage for managed-vCluster workload containers."
+  },
   {
     section: "processes",
     usage: "ps list [--worker <label>]",
@@ -259,6 +276,7 @@ const HELP_SECTION_ORDER = [
   "branches",
   "envs",
   "sessions",
+  "kubernetes",
   "processes",
   "shell",
   "agents",
@@ -271,6 +289,7 @@ const HELP_SECTION_TITLES = {
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  kubernetes: "Kubernetes",
   processes: "Processes",
   shell: "Shell",
   agents: "Agents",
@@ -935,6 +954,36 @@ function parseRecentSessionArgs(args) {
   if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error("--limit must be an integer between 1 and 200");
   return { limit };
 }
+function parseK8sUsageArgs(args) {
+  const parsed = { window: "24h" };
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const option = ["--namespace", "--workload", "--container", "--window"].find(
+      (candidate) => arg === candidate || arg.startsWith(`${candidate}=`)
+    );
+    if (!option) throw new Error(`Unknown k8s usage argument: ${arg}`);
+    if (seen.has(option)) throw new Error(`Use ${option} only once`);
+    seen.add(option);
+    const inlineValue = parseLongOptionWithEquals(arg, option);
+    const candidateValue = inlineValue ?? args[index + 1];
+    if (!candidateValue || candidateValue.startsWith("--")) throw new Error(`Missing value for ${option}`);
+    const value = candidateValue;
+    if (inlineValue === void 0) index += 1;
+    if (option === "--window") {
+      if (value !== "24h") throw new Error("--window currently supports only 24h");
+      parsed.window = value;
+    } else if (option === "--namespace") {
+      parsed.namespace = value;
+    } else if (option === "--workload") {
+      parsed.workload = value;
+    } else {
+      parsed.container = value;
+    }
+  }
+  return parsed;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -1096,6 +1145,145 @@ Error: ${result.error}` : "";
   return `Workspace sync ${result.outcome} on ${result.workerLabel}; HEAD ${head}; ${result.diffSizeBytes} bytes.${discarded}${error}
 `;
 }
+function summarizeK8sHistory(history) {
+  if (history.envelope.length === 0) {
+    return {
+      cpuMinNanoCores: null,
+      cpuMaxNanoCores: null,
+      memoryMinBytes: null,
+      memoryMaxBytes: null,
+      sampleCount: 0
+    };
+  }
+  return {
+    cpuMinNanoCores: Math.min(...history.envelope.map((point) => point.cpuMinNanoCores)),
+    cpuMaxNanoCores: Math.max(...history.envelope.map((point) => point.cpuMaxNanoCores)),
+    memoryMinBytes: Math.min(...history.envelope.map((point) => point.memoryMinBytes)),
+    memoryMaxBytes: Math.max(...history.envelope.map((point) => point.memoryMaxBytes)),
+    sampleCount: history.envelope.reduce((total, point) => total + point.sampleCount, 0)
+  };
+}
+async function mapWithConcurrency(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+      while (nextIndex < items.length) {
+        const index = nextIndex++;
+        const item = items[index];
+        if (item !== void 0) results[index] = await fn(item);
+      }
+    })
+  );
+  return results;
+}
+async function collectK8sUsage(client, options) {
+  const resources = await client.k8s.resources();
+  const candidates = resources.workloads.flatMap((workload) => workload.containers.map((container) => ({ workload, container }))).filter(({ workload, container }) => {
+    const workloadMatches = !options.workload || options.workload === workload.name || options.workload === `${workload.namespace}/${workload.name}` || options.workload === workload.uid;
+    return (!options.namespace || options.namespace === workload.namespace) && workloadMatches && (!options.container || options.container === container.name);
+  }).sort(
+    (left, right) => left.workload.namespace.localeCompare(right.workload.namespace) || left.workload.name.localeCompare(right.workload.name) || left.container.name.localeCompare(right.container.name)
+  );
+  if (candidates.length === 0 && (options.namespace || options.workload || options.container)) {
+    throw new Error("No managed-vCluster workload containers matched the requested filters");
+  }
+  const entries = await mapWithConcurrency(candidates, 8, async ({ workload, container }) => {
+    const history = await client.k8s.resourceHistory({ workloadUid: workload.uid, containerName: container.name });
+    return {
+      workload: {
+        uid: workload.uid,
+        kind: workload.kind,
+        namespace: workload.namespace,
+        name: workload.name
+      },
+      container: {
+        name: container.name,
+        currentUsage: container.currentUsage,
+        pods: container.pods
+      },
+      summary: summarizeK8sHistory(history),
+      history
+    };
+  });
+  return {
+    window: options.window,
+    collectedAt: resources.collectedAt,
+    metricsFreshAt: resources.metricsFreshAt,
+    metricsStale: resources.metricsStale,
+    filters: {
+      namespace: options.namespace,
+      workload: options.workload,
+      container: options.container
+    },
+    entries
+  };
+}
+function formatDecimal(value) {
+  if (value >= 100) return value.toFixed(0);
+  if (value >= 10) return value.toFixed(1).replace(/\.0$/, "");
+  return value.toFixed(2).replace(/\.0+$/, "").replace(/(\.\d)0$/, "$1");
+}
+function formatK8sCpu(value) {
+  if (value === null) return "-";
+  const milliCores = value / 1e6;
+  return milliCores >= 1e3 ? `${formatDecimal(milliCores / 1e3)} cores` : `${formatDecimal(milliCores)}m`;
+}
+function formatK8sMemory(value) {
+  if (value === null) return "-";
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let amount = value;
+  let unitIndex = 0;
+  while (amount >= 1024 && unitIndex < units.length - 1) {
+    amount /= 1024;
+    unitIndex += 1;
+  }
+  return `${formatDecimal(amount)} ${units[unitIndex]}`;
+}
+function formatK8sCoverage(start, end) {
+  if (!start || !end) return "none";
+  const durationMs = Date.parse(end) - Date.parse(start);
+  if (!Number.isFinite(durationMs) || durationMs < 0) return "unknown";
+  const totalMinutes = Math.floor(durationMs / 6e4);
+  return `${Math.floor(totalMinutes / 60)}h ${String(totalMinutes % 60).padStart(2, "0")}m`;
+}
+function renderK8sUsageReport(report) {
+  const freshness = report.metricsFreshAt ?? "unavailable";
+  const lines = [`Metrics: ${report.metricsStale ? "stale" : "current"} (fresh at ${freshness})`, "Window: 24h"];
+  if (report.entries.length === 0) return `${lines.join("\n")}
+No managed-vCluster workload containers found.
+`;
+  const headers = [
+    "NAMESPACE",
+    "WORKLOAD",
+    "CONTAINER",
+    "PODS",
+    "CPU NOW",
+    "CPU 24H MIN/MAX",
+    "MEM NOW",
+    "MEM 24H MIN/MAX",
+    "COVERAGE",
+    "STATUS"
+  ];
+  const rows = report.entries.map((entry) => [
+    entry.workload.namespace,
+    `${entry.workload.kind}/${entry.workload.name}`,
+    entry.container.name,
+    String(entry.container.pods.length),
+    formatK8sCpu(entry.container.currentUsage.cpuNanoCores),
+    `${formatK8sCpu(entry.summary.cpuMinNanoCores)} / ${formatK8sCpu(entry.summary.cpuMaxNanoCores)}`,
+    formatK8sMemory(entry.container.currentUsage.memoryBytes),
+    `${formatK8sMemory(entry.summary.memoryMinBytes)} / ${formatK8sMemory(entry.summary.memoryMaxBytes)}`,
+    formatK8sCoverage(entry.history.coverageStart, entry.history.coverageEnd),
+    entry.history.stale ? "stale" : entry.history.incomplete ? "partial" : "complete"
+  ]);
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+  const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+  const separator = widths.map((width) => "-".repeat(width)).join("  ");
+  lines.push(formatRow(headers), separator, ...rows.map(formatRow));
+  return `${lines.join("\n")}
+`;
+}
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
@@ -1474,6 +1662,11 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, renderWorkspaceSync(result));
     return;
   }
+  if (first === "k8s" && second === "usage") {
+    const report = await collectK8sUsage(client, parseK8sUsageArgs(args.slice(2)));
+    write(report, renderK8sUsageReport(report));
+    return;
+  }
   if (first === "ps" && second === "list") {
     const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
     write(processes, renderProcessList(processes));
@@ -1722,6 +1915,12 @@ function resolveCommandExecution(options, rest) {
       text: PS_HELP_TEXT
     };
   }
+  if (command === "k8s" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: K8S_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1850,6 +2049,15 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
   }
+  if (command === "k8s") {
+    const subcommand = commandArgs[0];
+    if (subcommand !== "usage") throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
+    if (options.project || options.branch || options.session) {
+      throw new Error("Project, branch, and session scopes are not supported for `k8s usage`");
+    }
+    parseK8sUsageArgs(commandArgs.slice(1));
+    return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -2278,6 +2486,9 @@ async function main(argv = process.argv.slice(2)) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  collectK8sUsage,
+  formatK8sCpu,
+  formatK8sMemory,
   formatProcessAge,
   getCliHelpText,
   getR5dctlVersion,
@@ -2288,6 +2499,7 @@ async function main(argv = process.argv.slice(2)) {
   parseEnvFlags,
   parseEnvRequestResponseArgs,
   parseGlobalArgs,
+  parseK8sUsageArgs,
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
@@ -2298,6 +2510,7 @@ async function main(argv = process.argv.slice(2)) {
   renderConversationOverviewResponse,
   renderConversationResponse,
   renderConversationWorkResponse,
+  renderK8sUsageReport,
   renderProcessHistory,
   renderProcessInspection,
   renderProcessList,

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "type": "commonjs"
 }

package/dist/mjs/cli.mjs

@@ -69,6 +69,13 @@ const PS_HELP_TEXT = [
   "Use -p/--project, -b/--branch, or -s/--session to filter list and history.",
   ""
 ].join("\n");
+const K8S_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window=24h]",
+  "",
+  "Show current and 24-hour CPU and memory usage for managed-vCluster workload containers.",
+  ""
+].join("\n");
 const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth status", description: "Show the current authenticated user and credential source." },
   { section: "auth", usage: "auth logout", description: "Revoke the current credential and clear saved auth." },
@@ -164,6 +171,11 @@ const SHARED_HELP_ENTRIES = [
     usage: "-s <session-id> answer-env-request [-e KEY=value] [--context <text>]",
     description: "Answer a pending environment variable request with values, context, or both."
   },
+  {
+    section: "kubernetes",
+    usage: "k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window=24h]",
+    description: "Show current and 24-hour CPU and memory usage for managed-vCluster workload containers."
+  },
   {
     section: "processes",
     usage: "ps list [--worker <label>]",
@@ -202,6 +214,7 @@ const HELP_SECTION_ORDER = [
   "branches",
   "envs",
   "sessions",
+  "kubernetes",
   "processes",
   "shell",
   "agents",
@@ -214,6 +227,7 @@ const HELP_SECTION_TITLES = {
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  kubernetes: "Kubernetes",
   processes: "Processes",
   shell: "Shell",
   agents: "Agents",
@@ -878,6 +892,36 @@ function parseRecentSessionArgs(args) {
   if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error("--limit must be an integer between 1 and 200");
   return { limit };
 }
+function parseK8sUsageArgs(args) {
+  const parsed = { window: "24h" };
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const option = ["--namespace", "--workload", "--container", "--window"].find(
+      (candidate) => arg === candidate || arg.startsWith(`${candidate}=`)
+    );
+    if (!option) throw new Error(`Unknown k8s usage argument: ${arg}`);
+    if (seen.has(option)) throw new Error(`Use ${option} only once`);
+    seen.add(option);
+    const inlineValue = parseLongOptionWithEquals(arg, option);
+    const candidateValue = inlineValue ?? args[index + 1];
+    if (!candidateValue || candidateValue.startsWith("--")) throw new Error(`Missing value for ${option}`);
+    const value = candidateValue;
+    if (inlineValue === void 0) index += 1;
+    if (option === "--window") {
+      if (value !== "24h") throw new Error("--window currently supports only 24h");
+      parsed.window = value;
+    } else if (option === "--namespace") {
+      parsed.namespace = value;
+    } else if (option === "--workload") {
+      parsed.workload = value;
+    } else {
+      parsed.container = value;
+    }
+  }
+  return parsed;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     spawn("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -1039,6 +1083,145 @@ Error: ${result.error}` : "";
   return `Workspace sync ${result.outcome} on ${result.workerLabel}; HEAD ${head}; ${result.diffSizeBytes} bytes.${discarded}${error}
 `;
 }
+function summarizeK8sHistory(history) {
+  if (history.envelope.length === 0) {
+    return {
+      cpuMinNanoCores: null,
+      cpuMaxNanoCores: null,
+      memoryMinBytes: null,
+      memoryMaxBytes: null,
+      sampleCount: 0
+    };
+  }
+  return {
+    cpuMinNanoCores: Math.min(...history.envelope.map((point) => point.cpuMinNanoCores)),
+    cpuMaxNanoCores: Math.max(...history.envelope.map((point) => point.cpuMaxNanoCores)),
+    memoryMinBytes: Math.min(...history.envelope.map((point) => point.memoryMinBytes)),
+    memoryMaxBytes: Math.max(...history.envelope.map((point) => point.memoryMaxBytes)),
+    sampleCount: history.envelope.reduce((total, point) => total + point.sampleCount, 0)
+  };
+}
+async function mapWithConcurrency(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+      while (nextIndex < items.length) {
+        const index = nextIndex++;
+        const item = items[index];
+        if (item !== void 0) results[index] = await fn(item);
+      }
+    })
+  );
+  return results;
+}
+async function collectK8sUsage(client, options) {
+  const resources = await client.k8s.resources();
+  const candidates = resources.workloads.flatMap((workload) => workload.containers.map((container) => ({ workload, container }))).filter(({ workload, container }) => {
+    const workloadMatches = !options.workload || options.workload === workload.name || options.workload === `${workload.namespace}/${workload.name}` || options.workload === workload.uid;
+    return (!options.namespace || options.namespace === workload.namespace) && workloadMatches && (!options.container || options.container === container.name);
+  }).sort(
+    (left, right) => left.workload.namespace.localeCompare(right.workload.namespace) || left.workload.name.localeCompare(right.workload.name) || left.container.name.localeCompare(right.container.name)
+  );
+  if (candidates.length === 0 && (options.namespace || options.workload || options.container)) {
+    throw new Error("No managed-vCluster workload containers matched the requested filters");
+  }
+  const entries = await mapWithConcurrency(candidates, 8, async ({ workload, container }) => {
+    const history = await client.k8s.resourceHistory({ workloadUid: workload.uid, containerName: container.name });
+    return {
+      workload: {
+        uid: workload.uid,
+        kind: workload.kind,
+        namespace: workload.namespace,
+        name: workload.name
+      },
+      container: {
+        name: container.name,
+        currentUsage: container.currentUsage,
+        pods: container.pods
+      },
+      summary: summarizeK8sHistory(history),
+      history
+    };
+  });
+  return {
+    window: options.window,
+    collectedAt: resources.collectedAt,
+    metricsFreshAt: resources.metricsFreshAt,
+    metricsStale: resources.metricsStale,
+    filters: {
+      namespace: options.namespace,
+      workload: options.workload,
+      container: options.container
+    },
+    entries
+  };
+}
+function formatDecimal(value) {
+  if (value >= 100) return value.toFixed(0);
+  if (value >= 10) return value.toFixed(1).replace(/\.0$/, "");
+  return value.toFixed(2).replace(/\.0+$/, "").replace(/(\.\d)0$/, "$1");
+}
+function formatK8sCpu(value) {
+  if (value === null) return "-";
+  const milliCores = value / 1e6;
+  return milliCores >= 1e3 ? `${formatDecimal(milliCores / 1e3)} cores` : `${formatDecimal(milliCores)}m`;
+}
+function formatK8sMemory(value) {
+  if (value === null) return "-";
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let amount = value;
+  let unitIndex = 0;
+  while (amount >= 1024 && unitIndex < units.length - 1) {
+    amount /= 1024;
+    unitIndex += 1;
+  }
+  return `${formatDecimal(amount)} ${units[unitIndex]}`;
+}
+function formatK8sCoverage(start, end) {
+  if (!start || !end) return "none";
+  const durationMs = Date.parse(end) - Date.parse(start);
+  if (!Number.isFinite(durationMs) || durationMs < 0) return "unknown";
+  const totalMinutes = Math.floor(durationMs / 6e4);
+  return `${Math.floor(totalMinutes / 60)}h ${String(totalMinutes % 60).padStart(2, "0")}m`;
+}
+function renderK8sUsageReport(report) {
+  const freshness = report.metricsFreshAt ?? "unavailable";
+  const lines = [`Metrics: ${report.metricsStale ? "stale" : "current"} (fresh at ${freshness})`, "Window: 24h"];
+  if (report.entries.length === 0) return `${lines.join("\n")}
+No managed-vCluster workload containers found.
+`;
+  const headers = [
+    "NAMESPACE",
+    "WORKLOAD",
+    "CONTAINER",
+    "PODS",
+    "CPU NOW",
+    "CPU 24H MIN/MAX",
+    "MEM NOW",
+    "MEM 24H MIN/MAX",
+    "COVERAGE",
+    "STATUS"
+  ];
+  const rows = report.entries.map((entry) => [
+    entry.workload.namespace,
+    `${entry.workload.kind}/${entry.workload.name}`,
+    entry.container.name,
+    String(entry.container.pods.length),
+    formatK8sCpu(entry.container.currentUsage.cpuNanoCores),
+    `${formatK8sCpu(entry.summary.cpuMinNanoCores)} / ${formatK8sCpu(entry.summary.cpuMaxNanoCores)}`,
+    formatK8sMemory(entry.container.currentUsage.memoryBytes),
+    `${formatK8sMemory(entry.summary.memoryMinBytes)} / ${formatK8sMemory(entry.summary.memoryMaxBytes)}`,
+    formatK8sCoverage(entry.history.coverageStart, entry.history.coverageEnd),
+    entry.history.stale ? "stale" : entry.history.incomplete ? "partial" : "complete"
+  ]);
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+  const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+  const separator = widths.map((width) => "-".repeat(width)).join("  ");
+  lines.push(formatRow(headers), separator, ...rows.map(formatRow));
+  return `${lines.join("\n")}
+`;
+}
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
@@ -1417,6 +1600,11 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, renderWorkspaceSync(result));
     return;
   }
+  if (first === "k8s" && second === "usage") {
+    const report = await collectK8sUsage(client, parseK8sUsageArgs(args.slice(2)));
+    write(report, renderK8sUsageReport(report));
+    return;
+  }
   if (first === "ps" && second === "list") {
     const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
     write(processes, renderProcessList(processes));
@@ -1665,6 +1853,12 @@ function resolveCommandExecution(options, rest) {
       text: PS_HELP_TEXT
     };
   }
+  if (command === "k8s" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: K8S_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1793,6 +1987,15 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
   }
+  if (command === "k8s") {
+    const subcommand = commandArgs[0];
+    if (subcommand !== "usage") throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
+    if (options.project || options.branch || options.session) {
+      throw new Error("Project, branch, and session scopes are not supported for `k8s usage`");
+    }
+    parseK8sUsageArgs(commandArgs.slice(1));
+    return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -2220,6 +2423,9 @@ async function main(argv = process.argv.slice(2)) {
   }
 }
 export {
+  collectK8sUsage,
+  formatK8sCpu,
+  formatK8sMemory,
   formatProcessAge,
   getCliHelpText,
   getR5dctlVersion,
@@ -2230,6 +2436,7 @@ export {
   parseEnvFlags,
   parseEnvRequestResponseArgs,
   parseGlobalArgs,
+  parseK8sUsageArgs,
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
@@ -2240,6 +2447,7 @@ export {
   renderConversationOverviewResponse,
   renderConversationResponse,
   renderConversationWorkResponse,
+  renderK8sUsageReport,
   renderProcessHistory,
   renderProcessInspection,
   renderProcessList,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "type": "module"
 }

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessRun, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { R5dctlClient, type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessRun, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -65,8 +65,46 @@ export declare function parseShellArgs(args: string[]): {
 };
 export declare function parsePsListArgs(args: string[]): R5dctlProcessListInput;
 export declare function parsePsHistoryArgs(args: string[]): R5dctlProcessListInput;
+export type K8sUsageOptions = {
+    namespace?: string;
+    workload?: string;
+    container?: string;
+    window: "24h";
+};
+export declare function parseK8sUsageArgs(args: string[]): K8sUsageOptions;
 export declare function renderWorkspaceStatus(status: R5dctlWorkspaceStatus): string;
 export declare function renderWorkspaceSync(result: R5dctlWorkspaceSyncResult): string;
+export type K8sUsageSummary = {
+    cpuMinNanoCores: number | null;
+    cpuMaxNanoCores: number | null;
+    memoryMinBytes: number | null;
+    memoryMaxBytes: number | null;
+    sampleCount: number;
+};
+export type K8sUsageReport = {
+    window: "24h";
+    collectedAt: string;
+    metricsFreshAt: string | null;
+    metricsStale: boolean;
+    filters: Omit<K8sUsageOptions, "window">;
+    entries: Array<{
+        workload: Pick<R5dctlK8sWorkload, "uid" | "kind" | "namespace" | "name">;
+        container: {
+            name: string;
+            currentUsage: R5dctlK8sUsage;
+            pods: Array<R5dctlK8sUsage & {
+                podUid: string;
+                podName: string;
+            }>;
+        };
+        summary: K8sUsageSummary;
+        history: R5dctlK8sResourceHistory;
+    }>;
+};
+export declare function collectK8sUsage(client: Pick<R5dctlClient, "k8s">, options: K8sUsageOptions): Promise<K8sUsageReport>;
+export declare function formatK8sCpu(value: number | null): string;
+export declare function formatK8sMemory(value: number | null): string;
+export declare function renderK8sUsageReport(report: K8sUsageReport): string;
 export declare function formatProcessAge(startedAt: string, nowMs?: number): string;
 export declare function renderProcessList(processes: R5dctlProcessRun[], nowMs?: number): string;
 export declare function renderProcessHistory(processes: R5dctlProcessRun[], nowMs?: number): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "type": "module",
   "main": "./dist/cjs/cli.cjs",
   "module": "./dist/mjs/cli.mjs",
@@ -26,7 +26,7 @@
     "r5dctl": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.49",
+    "@ricsam/r5d-api": "^0.0.50",
     "dotenv": "^17",
     "ws": "^8.18.3"
   },