@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/utils/resourceMonitor/readCpuResourceUsage.ts

@@ -0,0 +1,75 @@
+import os from 'node:os';
+
+import { DEFAULT_PROCESS_CPU_SAMPLE_DURATION_MS } from './resourceMonitorConstants';
+import { waitForResourceMonitorSample } from './waitForResourceMonitorSample';
+import type { CpuResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Options for reading CPU usage.
+ */
+type ReadCpuResourceUsageOptions = {
+    /**
+     * Whether the current Node.js process CPU usage should be sampled.
+     */
+    readonly isProcessUsageSampled: boolean;
+
+    /**
+     * Optional process CPU sampling duration.
+     */
+    readonly sampleDurationMs?: number;
+};
+
+/**
+ * Reads platform load average and optionally samples current process CPU usage.
+ *
+ * @param options - CPU reader options.
+ * @returns CPU usage snapshot.
+ */
+export async function readCpuResourceUsage({
+    isProcessUsageSampled,
+    sampleDurationMs = DEFAULT_PROCESS_CPU_SAMPLE_DURATION_MS,
+}: ReadCpuResourceUsageOptions): Promise<CpuResourceUsage> {
+    const coreCount = Math.max(os.cpus().length, 1);
+    const isLoadAverageAvailable = process.platform !== 'win32';
+    const [averageLoadOneMinute, averageLoadFiveMinutes, averageLoadFifteenMinutes] = isLoadAverageAvailable
+        ? os.loadavg()
+        : [null, null, null];
+    const loadRatio = averageLoadOneMinute === null ? null : averageLoadOneMinute / coreCount;
+    const processUsageRatio = isProcessUsageSampled
+        ? await sampleProcessCpuUsageRatio(coreCount, sampleDurationMs)
+        : null;
+
+    return {
+        coreCount,
+        averageLoadOneMinute,
+        averageLoadFiveMinutes,
+        averageLoadFifteenMinutes,
+        loadRatio,
+        processUsageRatio,
+    };
+}
+
+/**
+ * Samples current Node.js process CPU usage over a short interval.
+ *
+ * @param coreCount - Logical CPU core count.
+ * @param sampleDurationMs - Sampling duration in milliseconds.
+ * @returns Process CPU ratio across all logical cores.
+ */
+async function sampleProcessCpuUsageRatio(coreCount: number, sampleDurationMs: number): Promise<number | null> {
+    const startedUsage = process.cpuUsage();
+    const startedAtNanoseconds = process.hrtime.bigint();
+
+    await waitForResourceMonitorSample(sampleDurationMs);
+
+    const elapsedMicroseconds = Number(process.hrtime.bigint() - startedAtNanoseconds) / 1000;
+    if (!Number.isFinite(elapsedMicroseconds) || elapsedMicroseconds <= 0) {
+        return null;
+    }
+
+    const usage = process.cpuUsage(startedUsage);
+    const usedMicroseconds = usage.user + usage.system;
+    const processUsageRatio = usedMicroseconds / elapsedMicroseconds / Math.max(coreCount, 1);
+
+    return Number.isFinite(processUsageRatio) ? Math.max(processUsageRatio, 0) : null;
+}

package/apps/agents-server/src/utils/resourceMonitor/readDiskResourceUsage.ts

@@ -0,0 +1,42 @@
+import { statfs } from 'node:fs/promises';
+
+import type { DiskResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Reads disk usage for the filesystem that hosts the server process.
+ *
+ * @param inspectedPath - Filesystem path to inspect.
+ * @returns Disk usage snapshot.
+ */
+export async function readDiskResourceUsage(inspectedPath: string = process.cwd()): Promise<DiskResourceUsage> {
+    try {
+        const fileSystemStats = await statfs(inspectedPath);
+        const blockSize = fileSystemStats.bsize;
+        const totalBytes = fileSystemStats.blocks * blockSize;
+        const freeBytes = fileSystemStats.bfree * blockSize;
+        const availableBytes = fileSystemStats.bavail * blockSize;
+        const usedBytes = Math.max(totalBytes - freeBytes, 0);
+
+        return {
+            inspectedPath,
+            totalBytes,
+            freeBytes,
+            availableBytes,
+            usedBytes,
+            usedRatio: totalBytes > 0 ? usedBytes / totalBytes : null,
+            availableRatio: totalBytes > 0 ? availableBytes / totalBytes : null,
+            errorMessage: null,
+        };
+    } catch (error) {
+        return {
+            inspectedPath,
+            totalBytes: null,
+            freeBytes: null,
+            availableBytes: null,
+            usedBytes: null,
+            usedRatio: null,
+            availableRatio: null,
+            errorMessage: error instanceof Error ? error.message : 'Disk usage is not available.',
+        };
+    }
+}

package/apps/agents-server/src/utils/resourceMonitor/readMemoryResourceUsage.ts

@@ -0,0 +1,28 @@
+import os from 'node:os';
+
+import type { MemoryResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Reads current host and process memory usage.
+ *
+ * @returns Memory usage snapshot.
+ */
+export function readMemoryResourceUsage(): MemoryResourceUsage {
+    const totalBytes = os.totalmem();
+    const freeBytes = os.freemem();
+    const usedBytes = Math.max(totalBytes - freeBytes, 0);
+    const memoryUsage = process.memoryUsage();
+
+    return {
+        totalBytes,
+        freeBytes,
+        usedBytes,
+        usedRatio: totalBytes > 0 ? usedBytes / totalBytes : 0,
+        availableRatio: totalBytes > 0 ? freeBytes / totalBytes : 0,
+        processRssBytes: memoryUsage.rss,
+        processHeapUsedBytes: memoryUsage.heapUsed,
+        processHeapTotalBytes: memoryUsage.heapTotal,
+        processExternalBytes: memoryUsage.external,
+        processArrayBuffersBytes: memoryUsage.arrayBuffers ?? 0,
+    };
+}

package/apps/agents-server/src/utils/resourceMonitor/readNetworkResourceUsage.ts

@@ -0,0 +1,271 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+
+import { DEFAULT_NETWORK_SAMPLE_DURATION_MS } from './resourceMonitorConstants';
+import { waitForResourceMonitorSample } from './waitForResourceMonitorSample';
+import type { NetworkInterfaceResourceUsage, NetworkResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Linux network counter source.
+ */
+const LINUX_NETWORK_COUNTERS_PATH = '/proc/net/dev';
+
+/**
+ * Loopback interface omitted from host traffic totals.
+ */
+const LOOPBACK_NETWORK_INTERFACE_NAME = 'lo';
+
+/**
+ * Field index containing transmitted bytes in `/proc/net/dev`.
+ */
+const TRANSMITTED_BYTES_FIELD_INDEX = 8;
+
+/**
+ * Raw traffic counters read from the operating system.
+ */
+type NetworkTrafficCounter = {
+    readonly name: string;
+    readonly receivedBytes: number;
+    readonly transmittedBytes: number;
+};
+
+/**
+ * Result of reading traffic counters from the host.
+ */
+type NetworkTrafficCounterReadResult = {
+    readonly counters: ReadonlyArray<NetworkTrafficCounter> | null;
+    readonly errorMessage: string | null;
+};
+
+/**
+ * Reads network usage with current traffic rates when host counters are available.
+ *
+ * @param sampleDurationMs - Sampling duration used for byte-per-second rates.
+ * @returns Network usage snapshot.
+ */
+export async function readNetworkResourceUsage(
+    sampleDurationMs: number = DEFAULT_NETWORK_SAMPLE_DURATION_MS,
+): Promise<NetworkResourceUsage> {
+    const interfaceSummary = readNetworkInterfaceSummary();
+    const firstRead = await readLinuxNetworkTrafficCounters();
+
+    if (!firstRead.counters) {
+        return createUnavailableNetworkResourceUsage(interfaceSummary, firstRead.errorMessage);
+    }
+
+    const isRateSampled = sampleDurationMs > 0;
+    if (!isRateSampled) {
+        return createAvailableNetworkResourceUsage({
+            interfaceSummary,
+            counters: firstRead.counters,
+            previousCounters: null,
+            elapsedSeconds: null,
+            errorMessage: null,
+        });
+    }
+
+    const startedAtNanoseconds = process.hrtime.bigint();
+    await waitForResourceMonitorSample(sampleDurationMs);
+    const secondRead = await readLinuxNetworkTrafficCounters();
+    const elapsedSeconds = Number(process.hrtime.bigint() - startedAtNanoseconds) / 1_000_000_000;
+
+    if (!secondRead.counters) {
+        return createAvailableNetworkResourceUsage({
+            interfaceSummary,
+            counters: firstRead.counters,
+            previousCounters: null,
+            elapsedSeconds: null,
+            errorMessage: secondRead.errorMessage,
+        });
+    }
+
+    return createAvailableNetworkResourceUsage({
+        interfaceSummary,
+        counters: secondRead.counters,
+        previousCounters: firstRead.counters,
+        elapsedSeconds: Number.isFinite(elapsedSeconds) && elapsedSeconds > 0 ? elapsedSeconds : null,
+        errorMessage: null,
+    });
+}
+
+/**
+ * Reads interface and address counts from Node.js network metadata.
+ *
+ * @returns Network interface summary.
+ */
+function readNetworkInterfaceSummary(): Pick<NetworkResourceUsage, 'networkInterfaceCount' | 'networkAddressCount'> {
+    const networkInterfaces = os.networkInterfaces();
+    const interfaceNames = Object.keys(networkInterfaces);
+    const networkAddressCount = Object.values(networkInterfaces).reduce(
+        (count, addresses) => count + (addresses?.length ?? 0),
+        0,
+    );
+
+    return {
+        networkInterfaceCount: interfaceNames.length,
+        networkAddressCount,
+    };
+}
+
+/**
+ * Reads Linux traffic counters.
+ *
+ * @returns Traffic counters or an unavailable result.
+ */
+async function readLinuxNetworkTrafficCounters(): Promise<NetworkTrafficCounterReadResult> {
+    if (process.platform !== 'linux') {
+        return {
+            counters: null,
+            errorMessage: 'Traffic counters are available only on Linux hosts.',
+        };
+    }
+
+    try {
+        const content = await readFile(LINUX_NETWORK_COUNTERS_PATH, 'utf8');
+        return {
+            counters: parseLinuxNetworkTrafficCounters(content),
+            errorMessage: null,
+        };
+    } catch (error) {
+        return {
+            counters: null,
+            errorMessage: error instanceof Error ? error.message : 'Traffic counters are not available.',
+        };
+    }
+}
+
+/**
+ * Parses `/proc/net/dev` content into traffic counters.
+ *
+ * @param content - Raw `/proc/net/dev` file content.
+ * @returns Parsed non-loopback traffic counters.
+ */
+function parseLinuxNetworkTrafficCounters(content: string): ReadonlyArray<NetworkTrafficCounter> {
+    return content
+        .split('\n')
+        .slice(2)
+        .map(parseLinuxNetworkTrafficCounterLine)
+        .filter((counter): counter is NetworkTrafficCounter => counter !== null);
+}
+
+/**
+ * Parses one `/proc/net/dev` interface line.
+ *
+ * @param line - Raw interface line.
+ * @returns Traffic counter or `null` for unsupported lines.
+ */
+function parseLinuxNetworkTrafficCounterLine(line: string): NetworkTrafficCounter | null {
+    const separatorIndex = line.indexOf(':');
+    if (separatorIndex === -1) {
+        return null;
+    }
+
+    const name = line.slice(0, separatorIndex).trim();
+    if (!name || name === LOOPBACK_NETWORK_INTERFACE_NAME) {
+        return null;
+    }
+
+    const fields = line
+        .slice(separatorIndex + 1)
+        .trim()
+        .split(/\s+/);
+    const receivedBytes = Number(fields[0]);
+    const transmittedBytes = Number(fields[TRANSMITTED_BYTES_FIELD_INDEX]);
+    const isCounterValid = Number.isFinite(receivedBytes) && Number.isFinite(transmittedBytes);
+
+    if (!isCounterValid) {
+        return null;
+    }
+
+    return {
+        name,
+        receivedBytes,
+        transmittedBytes,
+    };
+}
+
+/**
+ * Creates an unavailable network usage snapshot.
+ *
+ * @param interfaceSummary - Interface/address counts.
+ * @param errorMessage - Reason traffic counters are unavailable.
+ * @returns Network usage snapshot.
+ */
+function createUnavailableNetworkResourceUsage(
+    interfaceSummary: Pick<NetworkResourceUsage, 'networkInterfaceCount' | 'networkAddressCount'>,
+    errorMessage: string | null,
+): NetworkResourceUsage {
+    return {
+        isTrafficAvailable: false,
+        interfaces: [],
+        totalReceivedBytes: null,
+        totalTransmittedBytes: null,
+        totalReceivedBytesPerSecond: null,
+        totalTransmittedBytesPerSecond: null,
+        networkInterfaceCount: interfaceSummary.networkInterfaceCount,
+        networkAddressCount: interfaceSummary.networkAddressCount,
+        errorMessage,
+    };
+}
+
+/**
+ * Creates an available network usage snapshot.
+ *
+ * @param options - Counter and sampling options.
+ * @returns Network usage snapshot.
+ */
+function createAvailableNetworkResourceUsage(options: {
+    readonly interfaceSummary: Pick<NetworkResourceUsage, 'networkInterfaceCount' | 'networkAddressCount'>;
+    readonly counters: ReadonlyArray<NetworkTrafficCounter>;
+    readonly previousCounters: ReadonlyArray<NetworkTrafficCounter> | null;
+    readonly elapsedSeconds: number | null;
+    readonly errorMessage: string | null;
+}): NetworkResourceUsage {
+    const previousCounterByName = new Map(options.previousCounters?.map((counter) => [counter.name, counter]) ?? []);
+    const interfaces = options.counters.map((counter): NetworkInterfaceResourceUsage => {
+        const previousCounter = previousCounterByName.get(counter.name);
+        const receivedBytesPerSecond =
+            previousCounter && options.elapsedSeconds
+                ? Math.max(counter.receivedBytes - previousCounter.receivedBytes, 0) / options.elapsedSeconds
+                : null;
+        const transmittedBytesPerSecond =
+            previousCounter && options.elapsedSeconds
+                ? Math.max(counter.transmittedBytes - previousCounter.transmittedBytes, 0) / options.elapsedSeconds
+                : null;
+
+        return {
+            name: counter.name,
+            receivedBytes: counter.receivedBytes,
+            transmittedBytes: counter.transmittedBytes,
+            receivedBytesPerSecond,
+            transmittedBytesPerSecond,
+        };
+    });
+
+    return {
+        isTrafficAvailable: true,
+        interfaces,
+        totalReceivedBytes: interfaces.reduce((sum, item) => sum + item.receivedBytes, 0),
+        totalTransmittedBytes: interfaces.reduce((sum, item) => sum + item.transmittedBytes, 0),
+        totalReceivedBytesPerSecond: sumNullableRates(interfaces.map((item) => item.receivedBytesPerSecond)),
+        totalTransmittedBytesPerSecond: sumNullableRates(interfaces.map((item) => item.transmittedBytesPerSecond)),
+        networkInterfaceCount: options.interfaceSummary.networkInterfaceCount,
+        networkAddressCount: options.interfaceSummary.networkAddressCount,
+        errorMessage: options.errorMessage,
+    };
+}
+
+/**
+ * Sums rates while preserving `null` when no rate was available.
+ *
+ * @param rates - Nullable rates.
+ * @returns Sum or `null`.
+ */
+function sumNullableRates(rates: ReadonlyArray<number | null>): number | null {
+    const availableRates = rates.filter((rate): rate is number => rate !== null);
+    if (availableRates.length === 0) {
+        return null;
+    }
+
+    return availableRates.reduce((sum, rate) => sum + rate, 0);
+}

package/apps/agents-server/src/utils/resourceMonitor/readServerResourceMonitorSnapshot.ts

@@ -0,0 +1,53 @@
+import { cache } from 'react';
+
+import { readAgentProjectsResourceUsage } from './readAgentProjectsResourceUsage';
+import { readAgentProjectRuntimesResourceUsage } from './readAgentProjectRuntimesResourceUsage';
+import { readCpuResourceUsage } from './readCpuResourceUsage';
+import { readDiskResourceUsage } from './readDiskResourceUsage';
+import { readMemoryResourceUsage } from './readMemoryResourceUsage';
+import { readNetworkResourceUsage } from './readNetworkResourceUsage';
+import { resolveServerResourceWarningStatus } from './resolveServerResourceWarningStatus';
+import type { ServerResourceMonitorSnapshot, ServerResourceWarningStatus } from './resourceMonitorTypes';
+
+/**
+ * Reads a full resource monitor snapshot for the admin page.
+ *
+ * @returns Full resource monitor snapshot.
+ */
+export const readServerResourceMonitorSnapshot = cache(async (): Promise<ServerResourceMonitorSnapshot> => {
+    const [cpu, disk, network, projects, projectRuntimes] = await Promise.all([
+        readCpuResourceUsage({ isProcessUsageSampled: true }),
+        readDiskResourceUsage(),
+        readNetworkResourceUsage(),
+        readAgentProjectsResourceUsage(),
+        readAgentProjectRuntimesResourceUsage(),
+    ]);
+    const memory = readMemoryResourceUsage();
+    const warningStatus = resolveServerResourceWarningStatus({ cpu, memory, disk });
+
+    return {
+        measuredAt: new Date().toISOString(),
+        cpu,
+        memory,
+        disk,
+        network,
+        projects,
+        projectRuntimes,
+        warningStatus,
+    };
+});
+
+/**
+ * Reads the lightweight warning status used by the header menu.
+ *
+ * @returns Current resource warning status.
+ */
+export const readServerResourceWarningStatus = cache(async (): Promise<ServerResourceWarningStatus> => {
+    const [cpu, disk] = await Promise.all([
+        readCpuResourceUsage({ isProcessUsageSampled: false }),
+        readDiskResourceUsage(),
+    ]);
+    const memory = readMemoryResourceUsage();
+
+    return resolveServerResourceWarningStatus({ cpu, memory, disk });
+});

package/apps/agents-server/src/utils/resourceMonitor/resolveServerResourceWarningStatus.ts

@@ -0,0 +1,72 @@
+import {
+    CPU_LOAD_WARNING_RATIO,
+    DISK_AVAILABLE_WARNING_BYTES,
+    DISK_AVAILABLE_WARNING_RATIO,
+    MEMORY_AVAILABLE_WARNING_RATIO,
+} from './resourceMonitorConstants';
+import { formatResourceBytes, formatResourcePercentage } from './formatResourceMonitorValue';
+import type {
+    CpuResourceUsage,
+    DiskResourceUsage,
+    MemoryResourceUsage,
+    ServerResourceWarningIssue,
+    ServerResourceWarningStatus,
+} from './resourceMonitorTypes';
+
+/**
+ * Inputs required to resolve resource warning status.
+ */
+type ResolveServerResourceWarningStatusOptions = {
+    readonly cpu: CpuResourceUsage;
+    readonly memory: MemoryResourceUsage;
+    readonly disk: DiskResourceUsage;
+};
+
+/**
+ * Resolves whether the server is low on operational resources.
+ *
+ * @param options - Current resource usage.
+ * @returns Warning status for the header and monitor page.
+ */
+export function resolveServerResourceWarningStatus({
+    cpu,
+    memory,
+    disk,
+}: ResolveServerResourceWarningStatusOptions): ServerResourceWarningStatus {
+    const issues: ServerResourceWarningIssue[] = [];
+
+    if (cpu.loadRatio !== null && cpu.loadRatio >= CPU_LOAD_WARNING_RATIO) {
+        issues.push({
+            resource: 'cpu',
+            message: `CPU load is ${formatResourcePercentage(cpu.loadRatio)} of ${cpu.coreCount} logical cores.`,
+        });
+    }
+
+    if (memory.availableRatio <= MEMORY_AVAILABLE_WARNING_RATIO) {
+        issues.push({
+            resource: 'memory',
+            message: `Free memory is ${formatResourcePercentage(memory.availableRatio)} (${formatResourceBytes(
+                memory.freeBytes,
+            )}) of ${formatResourceBytes(memory.totalBytes)}.`,
+        });
+    }
+
+    if (
+        disk.availableBytes !== null &&
+        disk.availableRatio !== null &&
+        (disk.availableRatio <= DISK_AVAILABLE_WARNING_RATIO || disk.availableBytes <= DISK_AVAILABLE_WARNING_BYTES)
+    ) {
+        issues.push({
+            resource: 'disk',
+            message: `Available disk space is ${formatResourcePercentage(disk.availableRatio)} (${formatResourceBytes(
+                disk.availableBytes,
+            )}) on ${disk.inspectedPath}.`,
+        });
+    }
+
+    return {
+        isWarningShown: issues.length > 0,
+        issues,
+        warningMessages: issues.map((issue) => issue.message),
+    };
+}

package/apps/agents-server/src/utils/resourceMonitor/resourceMonitorConstants.ts

@@ -0,0 +1,29 @@
+/**
+ * CPU load ratio that triggers a resource pressure warning.
+ */
+export const CPU_LOAD_WARNING_RATIO = 0.9;
+
+/**
+ * Free memory ratio that triggers a resource pressure warning.
+ */
+export const MEMORY_AVAILABLE_WARNING_RATIO = 0.1;
+
+/**
+ * Available disk ratio that triggers a resource pressure warning.
+ */
+export const DISK_AVAILABLE_WARNING_RATIO = 0.1;
+
+/**
+ * Available disk byte floor that triggers a resource pressure warning.
+ */
+export const DISK_AVAILABLE_WARNING_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * Default CPU sample duration for process usage.
+ */
+export const DEFAULT_PROCESS_CPU_SAMPLE_DURATION_MS = 250;
+
+/**
+ * Default network sample duration for rate calculation.
+ */
+export const DEFAULT_NETWORK_SAMPLE_DURATION_MS = 250;