@promptbook/cli 0.113.0-1 → 0.113.0-10

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,47 @@
+import { cache } from 'react';
+
+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] = await Promise.all([
+        readCpuResourceUsage({ isProcessUsageSampled: true }),
+        readDiskResourceUsage(),
+        readNetworkResourceUsage(),
+    ]);
+    const memory = readMemoryResourceUsage();
+    const warningStatus = resolveServerResourceWarningStatus({ cpu, memory, disk });
+
+    return {
+        measuredAt: new Date().toISOString(),
+        cpu,
+        memory,
+        disk,
+        network,
+        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;

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

@@ -0,0 +1,155 @@
+/**
+ * Resource key tracked by the server resource monitor.
+ */
+export type ResourceMonitorResource = 'cpu' | 'memory' | 'disk';
+
+/**
+ * One warning issue detected by the resource monitor.
+ */
+export type ServerResourceWarningIssue = {
+    /**
+     * Resource that crossed a warning threshold.
+     */
+    readonly resource: ResourceMonitorResource;
+
+    /**
+     * Human-readable warning message.
+     */
+    readonly message: string;
+};
+
+/**
+ * Lightweight resource status safe to pass into client navigation.
+ */
+export type ServerResourceWarningStatus = {
+    /**
+     * Whether any monitored resource is currently under pressure.
+     */
+    readonly isWarningShown: boolean;
+
+    /**
+     * Individual resource pressure issues.
+     */
+    readonly issues: ReadonlyArray<ServerResourceWarningIssue>;
+
+    /**
+     * Human-readable warning messages.
+     */
+    readonly warningMessages: ReadonlyArray<string>;
+};
+
+/**
+ * Default empty resource warning status.
+ */
+export const RESOURCE_MONITOR_OK_WARNING_STATUS: ServerResourceWarningStatus = {
+    isWarningShown: false,
+    issues: [],
+    warningMessages: [],
+};
+
+/**
+ * CPU usage snapshot.
+ */
+export type CpuResourceUsage = {
+    /**
+     * Number of logical CPU cores visible to Node.js.
+     */
+    readonly coreCount: number;
+
+    /**
+     * One-minute system load average, or `null` when the platform does not expose it.
+     */
+    readonly averageLoadOneMinute: number | null;
+
+    /**
+     * Five-minute system load average, or `null` when the platform does not expose it.
+     */
+    readonly averageLoadFiveMinutes: number | null;
+
+    /**
+     * Fifteen-minute system load average, or `null` when the platform does not expose it.
+     */
+    readonly averageLoadFifteenMinutes: number | null;
+
+    /**
+     * One-minute load divided by logical CPU cores.
+     */
+    readonly loadRatio: number | null;
+
+    /**
+     * Current Node.js process CPU ratio sampled over a short interval.
+     */
+    readonly processUsageRatio: number | null;
+};
+
+/**
+ * Memory usage snapshot.
+ */
+export type MemoryResourceUsage = {
+    readonly totalBytes: number;
+    readonly freeBytes: number;
+    readonly usedBytes: number;
+    readonly usedRatio: number;
+    readonly availableRatio: number;
+    readonly processRssBytes: number;
+    readonly processHeapUsedBytes: number;
+    readonly processHeapTotalBytes: number;
+    readonly processExternalBytes: number;
+    readonly processArrayBuffersBytes: number;
+};
+
+/**
+ * Disk usage snapshot for the filesystem that hosts the server process.
+ */
+export type DiskResourceUsage = {
+    readonly inspectedPath: string;
+    readonly totalBytes: number | null;
+    readonly freeBytes: number | null;
+    readonly availableBytes: number | null;
+    readonly usedBytes: number | null;
+    readonly usedRatio: number | null;
+    readonly availableRatio: number | null;
+    readonly errorMessage: string | null;
+};
+
+/**
+ * Network traffic snapshot for one interface.
+ */
+export type NetworkInterfaceResourceUsage = {
+    readonly name: string;
+    readonly receivedBytes: number;
+    readonly transmittedBytes: number;
+    readonly receivedBytesPerSecond: number | null;
+    readonly transmittedBytesPerSecond: number | null;
+};
+
+/**
+ * Network traffic summary.
+ */
+export type NetworkResourceUsage = {
+    /**
+     * Whether traffic counters are available on this host.
+     */
+    readonly isTrafficAvailable: boolean;
+
+    readonly interfaces: ReadonlyArray<NetworkInterfaceResourceUsage>;
+    readonly totalReceivedBytes: number | null;
+    readonly totalTransmittedBytes: number | null;
+    readonly totalReceivedBytesPerSecond: number | null;
+    readonly totalTransmittedBytesPerSecond: number | null;
+    readonly networkInterfaceCount: number;
+    readonly networkAddressCount: number;
+    readonly errorMessage: string | null;
+};
+
+/**
+ * Full resource monitor snapshot rendered by `/admin/resource-monitor`.
+ */
+export type ServerResourceMonitorSnapshot = {
+    readonly measuredAt: string;
+    readonly cpu: CpuResourceUsage;
+    readonly memory: MemoryResourceUsage;
+    readonly disk: DiskResourceUsage;
+    readonly network: NetworkResourceUsage;
+    readonly warningStatus: ServerResourceWarningStatus;
+};

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

@@ -0,0 +1,11 @@
+/**
+ * Waits for a short sampling interval between resource counter reads.
+ *
+ * @param durationMs - Sampling duration in milliseconds.
+ * @returns Promise resolved after the duration elapses.
+ */
+export function waitForResourceMonitorSample(durationMs: number): Promise<void> {
+    return new Promise((resolve) => {
+        setTimeout(resolve, Math.max(0, durationMs));
+    });
+}

package/apps/agents-server/src/utils/shibbolethAuthentication/createShibbolethSamlClient.ts

@@ -0,0 +1,35 @@
+import { SAML, ValidateInResponseTo } from '@node-saml/node-saml';
+import {
+    SHIBBOLETH_ACCEPTED_CLOCK_SKEW_MS,
+    SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT,
+} from './shibbolethAuthenticationConstants';
+import type { ShibbolethAuthenticationConfiguration } from './shibbolethAuthenticationTypes';
+
+/**
+ * Creates a Node-SAML client for the resolved Shibboleth configuration.
+ *
+ * @param configuration - Resolved Shibboleth configuration with parsed IdP metadata.
+ * @returns Configured Node-SAML client.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export function createShibbolethSamlClient(configuration: ShibbolethAuthenticationConfiguration): SAML {
+    if (!configuration.identityProviderMetadata) {
+        throw new Error('Shibboleth Identity Provider metadata is not loaded.');
+    }
+
+    return new SAML({
+        callbackUrl: configuration.serviceProviderUrls.assertionConsumerServiceUrl,
+        entryPoint: configuration.identityProviderMetadata.singleSignOnServiceUrl,
+        issuer: configuration.serviceProviderUrls.entityId,
+        audience: configuration.serviceProviderUrls.entityId,
+        idpCert: [...configuration.identityProviderMetadata.signingCertificates],
+        identifierFormat: SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT,
+        wantAssertionsSigned: true,
+        wantAuthnResponseSigned: false,
+        acceptedClockSkewMs: SHIBBOLETH_ACCEPTED_CLOCK_SKEW_MS,
+        validateInResponseTo: ValidateInResponseTo.never,
+        disableRequestedAuthnContext: true,
+        signatureAlgorithm: 'sha256',
+    });
+}

package/apps/agents-server/src/utils/shibbolethAuthentication/createShibbolethServiceProviderMetadataXml.ts

@@ -0,0 +1,25 @@
+import { generateServiceProviderMetadata } from '@node-saml/node-saml';
+import { SHIBBOLETH_AUTHENTICATION_METADATA_KEYS } from '@/src/constants/shibbolethAuth';
+import { getMetadataMap } from '@/src/database/getMetadata';
+import { SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT } from './shibbolethAuthenticationConstants';
+import { resolveShibbolethServiceProviderUrls } from './resolveShibbolethServiceProviderUrls';
+
+/**
+ * Creates Service Provider metadata XML for the current Agents Server deployment.
+ *
+ * @param requestUrl - URL of the current metadata route request.
+ * @returns Service Provider metadata XML suitable for the Shibboleth IdP admin.
+ *
+ * @private function of `shibbolethAuthentication`
+ */
+export async function createShibbolethServiceProviderMetadataXml(requestUrl: string): Promise<string> {
+    const metadata = await getMetadataMap(SHIBBOLETH_AUTHENTICATION_METADATA_KEYS);
+    const serviceProviderUrls = resolveShibbolethServiceProviderUrls(requestUrl, metadata);
+
+    return generateServiceProviderMetadata({
+        issuer: serviceProviderUrls.entityId,
+        callbackUrl: serviceProviderUrls.assertionConsumerServiceUrl,
+        identifierFormat: SHIBBOLETH_PERSISTENT_NAME_ID_FORMAT,
+        wantAssertionsSigned: true,
+    });
+}