agl 1.0.17 → 21.0.2

package/ts/classes.resourcecoordinator.ts

@@ -0,0 +1,436 @@
+import {
+  controllerRuntimeIdKey,
+  type TControllerResource,
+  type TControllerSessionId,
+} from '../ts_interfaces/index.js';
+import type { SmartDataAuthStore } from './classes.authstore.js';
+import type { IControllerResourceDocument } from './interfaces.projects.js';
+import {
+  type IFlexBrowserResourceDescriptor,
+} from './interfaces.flexipc.js';
+
+export interface IControllerResourceRuntimeHost {
+  startResource(
+    resourceArg: IControllerResourceDocument,
+    signalArg: AbortSignal,
+  ): Promise<void>;
+  stopResource(
+    resourceArg: IControllerResourceDocument,
+    signalArg: AbortSignal,
+  ): Promise<void>;
+  isRunning(resourceArg: IControllerResourceDocument): boolean;
+  isAvailable(): boolean;
+  renameResource?(resourceArg: IControllerResourceDocument): Promise<void>;
+  reconcileAttachment(
+    resourceArg: IControllerResourceDocument,
+    signalArg: AbortSignal,
+  ): Promise<void>;
+  retireResource(
+    resourceArg: IControllerResourceDocument,
+    signalArg: AbortSignal,
+  ): Promise<void>;
+}
+
+export interface IControllerResourceCoordinatorOptions {
+  store: Pick<
+    SmartDataAuthStore,
+    | 'listResources'
+    | 'listRecoverableResources'
+    | 'createResource'
+    | 'renameResource'
+    | 'beginResourceAttachmentTransition'
+    | 'commitResourceAttachmentTransition'
+    | 'beginResourceRetirement'
+    | 'completeResourceRetirement'
+  >;
+  terminalHost: IControllerResourceRuntimeHost;
+  browserHost: IControllerResourceRuntimeHost;
+  isFlexHarnessAvailable(): boolean;
+}
+
+export class ControllerResourceUnavailableError extends Error {
+  public readonly code = 'resource_unavailable';
+
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'ControllerResourceUnavailableError';
+  }
+}
+
+export class ControllerProjectHasResourcesError extends Error {
+  public readonly code = 'project_has_resources';
+
+  constructor(public readonly resourceIds: string[]) {
+    super('Retire every project resource before removing the project.');
+    this.name = 'ControllerProjectHasResourcesError';
+  }
+}
+
+interface IProjectMutationState {
+  tail: Promise<void>;
+  admissionOpen: boolean;
+  removed: boolean;
+}
+
+const sessionIdsEqual = (
+  leftArg: TControllerSessionId | null,
+  rightArg: TControllerSessionId | null,
+): boolean => leftArg === null
+  ? rightArg === null
+  : rightArg !== null && controllerRuntimeIdKey(leftArg) === controllerRuntimeIdKey(rightArg);
+
+export class ControllerResourceCoordinator {
+  private readonly projectStates = new Map<string, IProjectMutationState>();
+  private readonly deletingSessions = new Set<string>();
+
+  constructor(private readonly options: IControllerResourceCoordinatorOptions) {}
+
+  public async listResources(projectIdArg: string): Promise<TControllerResource[]> {
+    const resources = await this.options.store.listResources(projectIdArg);
+    return resources.map((resource) => this.toPublicResource(resource));
+  }
+
+  public async requireResourceKind(
+    projectIdArg: string,
+    resourceIdArg: string,
+    kindArg: IControllerResourceDocument['kind'],
+  ): Promise<boolean> {
+    return this.runProjectMutation(projectIdArg, async () => {
+      const resource = (await this.options.store.listResources(projectIdArg))
+        .find((entry) => entry.id === resourceIdArg);
+      if (!resource) return false;
+      if (resource.kind !== kindArg) {
+        throw new ControllerResourceUnavailableError(`The requested ${kindArg} resource is unavailable.`);
+      }
+      return true;
+    });
+  }
+
+  public async createResource(
+    inputArg: Parameters<SmartDataAuthStore['createResource']>[0],
+    signalArg: AbortSignal,
+  ): Promise<TControllerResource> {
+    return this.runProjectMutation(inputArg.projectId, async () => {
+      const resource = await this.options.store.createResource(inputArg);
+      await this.hostFor(resource).startResource(resource, signalArg);
+      const current = (await this.options.store.listResources(inputArg.projectId))
+        .find((entry) => entry.id === resource.id) ?? resource;
+      return this.toPublicResource(current);
+    });
+  }
+
+  public async renameResource(
+    projectIdArg: string,
+    resourceIdArg: string,
+    titleArg: string,
+  ): Promise<TControllerResource> {
+    return this.runProjectMutation(projectIdArg, async () => {
+      const resource = await this.options.store.renameResource(projectIdArg, resourceIdArg, titleArg);
+      await this.hostFor(resource).renameResource?.(resource);
+      return this.toPublicResource(resource);
+    });
+  }
+
+  public async changeAttachment(inputArg: {
+    projectId: string;
+    resourceId: string;
+    sessionId: TControllerSessionId | null;
+    expectedAttachmentRevision: number;
+    signal: AbortSignal;
+  }): Promise<TControllerResource> {
+    return this.runProjectMutation(inputArg.projectId, async () => {
+      if (
+        inputArg.sessionId
+        && this.deletingSessions.has(this.sessionKey(inputArg.projectId, inputArg.sessionId))
+      ) {
+        throw new ControllerResourceUnavailableError('The target session is being deleted.');
+      }
+      const pending = await this.options.store.beginResourceAttachmentTransition(
+        inputArg.projectId,
+        inputArg.resourceId,
+        inputArg.sessionId,
+        inputArg.expectedAttachmentRevision,
+      );
+      return this.toPublicResource(await this.reconcilePendingAttachment(pending, inputArg.signal));
+    });
+  }
+
+  public async retireResource(
+    projectIdArg: string,
+    resourceIdArg: string,
+    signalArg: AbortSignal,
+  ): Promise<void> {
+    await this.runProjectMutation(projectIdArg, async () => {
+      const retiring = await this.options.store.beginResourceRetirement(projectIdArg, resourceIdArg);
+      if (retiring.lifecycle === 'retired') return;
+      await this.hostFor(retiring).retireResource(retiring, signalArg);
+      await this.options.store.completeResourceRetirement(projectIdArg, resourceIdArg);
+    });
+  }
+
+  public async startResource(
+    projectIdArg: string,
+    resourceIdArg: string,
+    signalArg: AbortSignal,
+  ): Promise<TControllerResource> {
+    return this.runProjectMutation(projectIdArg, async () => {
+      const resource = (await this.options.store.listResources(projectIdArg))
+        .find((entry) => entry.id === resourceIdArg);
+      if (!resource || resource.lifecycle !== 'active' || resource.pendingAttachment) {
+        throw new ControllerResourceUnavailableError('The resource cannot be started now.');
+      }
+      await this.hostFor(resource).startResource(resource, signalArg);
+      const current = (await this.options.store.listResources(projectIdArg))
+        .find((entry) => entry.id === resourceIdArg) ?? resource;
+      return this.toPublicResource(current);
+    });
+  }
+
+  public async stopResource(
+    projectIdArg: string,
+    resourceIdArg: string,
+    signalArg: AbortSignal,
+  ): Promise<TControllerResource> {
+    return this.runProjectMutation(projectIdArg, async () => {
+      const resource = (await this.options.store.listResources(projectIdArg))
+        .find((entry) => entry.id === resourceIdArg);
+      if (!resource || resource.lifecycle !== 'active') {
+        throw new ControllerResourceUnavailableError('The resource cannot be stopped now.');
+      }
+      await this.hostFor(resource).stopResource(resource, signalArg);
+      const current = (await this.options.store.listResources(projectIdArg))
+        .find((entry) => entry.id === resourceIdArg) ?? resource;
+      return this.toPublicResource(current);
+    });
+  }
+
+  public async recover(signalArg: AbortSignal): Promise<void> {
+    for (const resource of await this.options.store.listRecoverableResources()) {
+      signalArg.throwIfAborted();
+      await this.runProjectMutation(resource.projectId, async () => {
+        if (resource.lifecycle === 'retiring') {
+          await this.hostFor(resource).retireResource(resource, signalArg);
+          await this.options.store.completeResourceRetirement(resource.projectId, resource.id);
+          return;
+        }
+        if (resource.pendingAttachment) {
+          await this.reconcilePendingAttachment(resource, signalArg);
+          return;
+        }
+        await this.hostFor(resource).reconcileAttachment(resource, signalArg);
+      });
+    }
+  }
+
+  public async withSessionDeletion<T>(
+    projectIdArg: string,
+    sessionIdArg: TControllerSessionId,
+    signalArg: AbortSignal,
+    deleteArg: () => Promise<T>,
+  ): Promise<T> {
+    const sessionKey = this.sessionKey(projectIdArg, sessionIdArg);
+    if (this.deletingSessions.has(sessionKey)) {
+      throw new ControllerResourceUnavailableError('The session is already being deleted.');
+    }
+    this.deletingSessions.add(sessionKey);
+    try {
+      await this.runProjectMutation(projectIdArg, async () => {
+        const resources = await this.options.store.listResources(projectIdArg);
+        for (let resource of resources) {
+          if (resource.pendingAttachment) {
+            resource = await this.reconcilePendingAttachment(resource, signalArg);
+          }
+          if (!sessionIdsEqual(resource.sessionId, sessionIdArg)) continue;
+          const pending = await this.options.store.beginResourceAttachmentTransition(
+            projectIdArg,
+            resource.id,
+            null,
+            resource.attachmentRevision,
+          );
+          await this.reconcilePendingAttachment(pending, signalArg);
+        }
+      });
+      return await deleteArg();
+    } finally {
+      this.deletingSessions.delete(sessionKey);
+    }
+  }
+
+  public async withProjectRemovalGuard<T>(
+    projectIdArg: string,
+    removeArg: () => Promise<T>,
+  ): Promise<T> {
+    const state = this.projectState(projectIdArg);
+    if (!state.admissionOpen || state.removed) {
+      throw new ControllerResourceUnavailableError('The project is not accepting resource operations.');
+    }
+    state.admissionOpen = false;
+    await state.tail;
+    const resources = await this.options.store.listResources(projectIdArg);
+    if (resources.length > 0) {
+      state.admissionOpen = true;
+      throw new ControllerProjectHasResourcesError(resources.map((resource) => resource.id));
+    }
+    try {
+      const result = await removeArg();
+      state.removed = true;
+      this.projectStates.delete(projectIdArg);
+      return result;
+    } catch (errorArg) {
+      state.admissionOpen = true;
+      throw errorArg;
+    }
+  }
+
+  public async resolveFlexBrowserResources(
+    projectIdArg: string,
+    sessionIdArg: string,
+  ): Promise<IFlexBrowserResourceDescriptor[]> {
+    return this.runProjectMutation(projectIdArg, async () => (
+      (await this.options.store.listResources(projectIdArg))
+        .filter((resource) => (
+          resource.kind === 'browser'
+          && resource.lifecycle === 'active'
+          && resource.pendingAttachment === undefined
+          && resource.sessionId?.harnessId === 'flex'
+          && resource.sessionId.nativeId === sessionIdArg
+        ))
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((resource) => ({
+          resourceId: resource.id,
+          attachmentRevision: resource.attachmentRevision,
+        }))
+    ));
+  }
+
+  public async requireFlexBrowserResource(inputArg: {
+    projectId: string;
+    sessionId: string;
+    resourceId: string;
+    attachmentRevision: number;
+  }): Promise<IControllerResourceDocument> {
+    return this.runProjectMutation(inputArg.projectId, async () => {
+      const resource = (await this.options.store.listResources(inputArg.projectId))
+        .find((entry) => entry.id === inputArg.resourceId);
+      if (
+        !resource
+        || resource.kind !== 'browser'
+        || resource.lifecycle !== 'active'
+        || resource.pendingAttachment !== undefined
+        || resource.attachmentRevision !== inputArg.attachmentRevision
+        || resource.sessionId?.harnessId !== 'flex'
+        || resource.sessionId.nativeId !== inputArg.sessionId
+      ) throw new ControllerResourceUnavailableError('The browser attachment is no longer current.');
+      return resource;
+    });
+  }
+
+  private async reconcilePendingAttachment(
+    resourceArg: IControllerResourceDocument,
+    signalArg: AbortSignal,
+  ): Promise<IControllerResourceDocument> {
+    const pending = resourceArg.pendingAttachment;
+    if (!pending) return resourceArg;
+    const target: IControllerResourceDocument = {
+      ...resourceArg,
+      attachmentRevision: pending.attachmentRevision,
+      sessionId: pending.sessionId === null ? null : { ...pending.sessionId },
+    };
+    delete target.pendingAttachment;
+    await this.hostFor(resourceArg).reconcileAttachment(target, signalArg);
+    return this.options.store.commitResourceAttachmentTransition(
+      resourceArg.projectId,
+      resourceArg.id,
+      pending.operationId,
+    );
+  }
+
+  private toPublicResource(resourceArg: IControllerResourceDocument): TControllerResource {
+    const attachment = {
+      authorityId: resourceArg.attachmentAuthorityId,
+      revision: resourceArg.attachmentRevision,
+      sessionId: resourceArg.sessionId === null ? null : { ...resourceArg.sessionId },
+    };
+    const agentAvailability = resourceArg.pendingAttachment
+      ? 'transitioning' as const
+      : resourceArg.sessionId === null
+        ? 'detached' as const
+        : resourceArg.kind === 'browser'
+          ? resourceArg.sessionId?.harnessId === 'flex'
+            && this.options.browserHost.isAvailable()
+            && this.options.isFlexHarnessAvailable()
+            ? 'available' as const
+            : 'dependencyUnavailable' as const
+          : 'available' as const;
+    const base = {
+      id: resourceArg.id,
+      projectId: resourceArg.projectId,
+      kind: resourceArg.kind,
+      title: resourceArg.title,
+      lifecycle: resourceArg.lifecycle,
+      attachment,
+      agentAvailability,
+      createdAt: resourceArg.createdAt.getTime(),
+      updatedAt: resourceArg.updatedAt.getTime(),
+    };
+    if (resourceArg.kind === 'browser') {
+      return {
+        ...base,
+        kind: 'browser',
+        browserRuntimeState: this.options.browserHost.isAvailable() ? 'available' : 'unavailable',
+      };
+    }
+    const terminal = resourceArg.terminal!;
+    return {
+      ...base,
+      kind: 'terminal',
+      command: terminal.command,
+      cwd: terminal.cwd,
+      processState: this.options.terminalHost.isRunning(resourceArg) ? 'running' : 'stopped',
+      ...(terminal.stoppedAt === undefined ? {} : { stoppedAt: terminal.stoppedAt.getTime() }),
+      ...(terminal.lastExitCode === undefined ? {} : { lastExitCode: terminal.lastExitCode }),
+    };
+  }
+
+  private hostFor(resourceArg: IControllerResourceDocument): IControllerResourceRuntimeHost {
+    return resourceArg.kind === 'terminal' ? this.options.terminalHost : this.options.browserHost;
+  }
+
+  private projectState(projectIdArg: string): IProjectMutationState {
+    let state = this.projectStates.get(projectIdArg);
+    if (!state) {
+      state = { tail: Promise.resolve(), admissionOpen: true, removed: false };
+      this.projectStates.set(projectIdArg, state);
+    }
+    return state;
+  }
+
+  private runProjectMutation<T>(projectIdArg: string, operationArg: () => Promise<T>): Promise<T> {
+    const state = this.projectState(projectIdArg);
+    if (!state.admissionOpen || state.removed) {
+      return Promise.reject(new ControllerResourceUnavailableError(
+        'The project is not accepting resource operations.',
+      ));
+    }
+    const operation = state.tail.then(async () => {
+      if (!state.admissionOpen || state.removed) {
+        throw new ControllerResourceUnavailableError('The project stopped accepting resource operations.');
+      }
+      return operationArg();
+    });
+    const tail = operation.then(() => undefined, () => undefined);
+    state.tail = tail;
+    void tail.finally(() => {
+      if (
+        state.admissionOpen
+        && !state.removed
+        && state.tail === tail
+      ) this.projectStates.delete(projectIdArg);
+    });
+    return operation;
+  }
+
+  private sessionKey(projectIdArg: string, sessionIdArg: TControllerSessionId): string {
+    return `${projectIdArg}:${controllerRuntimeIdKey(sessionIdArg)}`;
+  }
+}

package/ts/classes.sessionintelligencereader.ts

@@ -0,0 +1,52 @@
+import * as plugins from './plugins.js';
+import type { IOpenCodeConnectionConfig } from './interfaces.opencode.js';
+
+export class SessionIntelligenceReader {
+  private readonly registry: plugins.crossharness.ConnectionRegistry;
+  private connectionId?: string;
+
+  constructor(private readonly config: IOpenCodeConnectionConfig) {
+    this.registry = new plugins.crossharness.ConnectionRegistry({
+      allowedServerUrls: [config.baseUrl],
+      maxConnections: 1,
+      openCodeCredentials: {
+        serverUrl: config.baseUrl,
+        username: config.username,
+        password: config.password,
+      },
+    });
+  }
+
+  public async init(signalArg?: AbortSignal): Promise<void> {
+    if (this.connectionId) throw new Error('The Session Intelligence reader is already initialized.');
+    const connection = await this.registry.connect(
+      'opencode',
+      this.config.baseUrl,
+      this.config.directory,
+      signalArg,
+    );
+    this.connectionId = connection.connectionId;
+  }
+
+  public listChats(limitArg: number): Promise<plugins.crossharness.IChatSummary[]> {
+    return this.connection().listChats(limitArg);
+  }
+
+  public readChat(
+    chatIdArg: string,
+    limitArg: number,
+    maxCharsArg: number,
+  ): Promise<plugins.crossharness.IChatTranscript> {
+    return this.connection().readChat(chatIdArg, limitArg, maxCharsArg);
+  }
+
+  public async close(): Promise<void> {
+    await this.registry.closeAll();
+    this.connectionId = undefined;
+  }
+
+  private connection(): plugins.crossharness.IHarnessConnection {
+    if (!this.connectionId) throw new Error('The Session Intelligence reader is not initialized.');
+    return this.registry.get(this.connectionId);
+  }
+}

package/ts/classes.systemmetricssampler.ts

@@ -0,0 +1,215 @@
+import * as plugins from './plugins.js';
+import type { IControllerSystemMetrics } from '../ts_interfaces/index.js';
+
+interface ISystemMetricsSource {
+  currentLoad: () => Promise<{ currentLoad: number }>;
+  mem: () => Promise<{ active: number; total: number }>;
+  networkInterfaces: () => Promise<Array<{
+    iface: string;
+    virtual: boolean;
+  }>>;
+  networkStats: (interfaces: string) => Promise<Array<{
+    rx_sec: number;
+    tx_sec: number;
+  }>>;
+}
+
+interface IRawSystemMetrics {
+  cpuUsagePercent?: unknown;
+  memoryUsedBytes?: unknown;
+  memoryTotalBytes?: unknown;
+  networkStats?: Array<{
+    rx_sec?: unknown;
+    tx_sec?: unknown;
+  }>;
+}
+
+interface ISystemMetricsSamplerOptions {
+  source?: ISystemMetricsSource;
+  now?: () => number;
+  sampleTimeoutMs?: number;
+}
+
+const cacheTtlMs = 1_000;
+const defaultSampleTimeoutMs = 2_000;
+
+const asNonNegativeNumber = (valueArg: unknown): number | null => (
+  typeof valueArg === 'number' && Number.isFinite(valueArg) && valueArg >= 0
+    ? valueArg
+    : null
+);
+
+const asPercentage = (valueArg: unknown): number | null => {
+  const value = asNonNegativeNumber(valueArg);
+  return value !== null && value <= 100 ? value : null;
+};
+
+const aggregateNetworkRate = (
+  statsArg: IRawSystemMetrics['networkStats'],
+  keyArg: 'rx_sec' | 'tx_sec',
+): number | null => {
+  if (!statsArg || statsArg.length === 0) return null;
+  let total = 0;
+  for (const stats of statsArg) {
+    const value = asNonNegativeNumber(stats[keyArg]);
+    if (value === null) return null;
+    total += value;
+  }
+  return Number.isFinite(total) ? total : null;
+};
+
+export const normalizeSystemMetrics = (
+  sampledAtArg: number,
+  rawArg: IRawSystemMetrics,
+): IControllerSystemMetrics => {
+  const memoryTotalBytes = asNonNegativeNumber(rawArg.memoryTotalBytes);
+  const memoryUsedCandidate = asNonNegativeNumber(rawArg.memoryUsedBytes);
+  const memoryUsedBytes = (
+    memoryUsedCandidate !== null
+    && memoryTotalBytes !== null
+    && memoryTotalBytes > 0
+    && memoryUsedCandidate <= memoryTotalBytes
+  ) ? memoryUsedCandidate : null;
+
+  return {
+    sampledAt: sampledAtArg,
+    cpuUsagePercent: asPercentage(rawArg.cpuUsagePercent),
+    memoryUsedBytes,
+    memoryTotalBytes: memoryTotalBytes !== null && memoryTotalBytes > 0
+      ? memoryTotalBytes
+      : null,
+    networkReceiveBytesPerSecond: aggregateNetworkRate(rawArg.networkStats, 'rx_sec'),
+    networkTransmitBytesPerSecond: aggregateNetworkRate(rawArg.networkStats, 'tx_sec'),
+  };
+};
+
+export class SystemMetricsSampler {
+  private readonly source: ISystemMetricsSource;
+  private readonly now: () => number;
+  private readonly sampleTimeoutMs: number;
+  private cachedSample: IControllerSystemMetrics | undefined;
+  private inFlightSample: Promise<IControllerSystemMetrics> | undefined;
+  private inFlightCpuRead: Promise<{ currentLoad: number }> | undefined;
+  private inFlightMemoryRead: Promise<{ active: number; total: number }> | undefined;
+  private inFlightNetworkRead: Promise<Array<{ rx_sec: number; tx_sec: number }>> | undefined;
+
+  constructor(optionsArg: ISystemMetricsSamplerOptions = {}) {
+    this.source = optionsArg.source ?? plugins.systeminformation;
+    this.now = optionsArg.now ?? Date.now;
+    this.sampleTimeoutMs = optionsArg.sampleTimeoutMs ?? defaultSampleTimeoutMs;
+  }
+
+  public async sample(): Promise<IControllerSystemMetrics> {
+    const now = this.now();
+    if (this.cachedSample && now - this.cachedSample.sampledAt < cacheTtlMs) {
+      return this.cachedSample;
+    }
+    if (this.inFlightSample) return this.inFlightSample;
+
+    const samplePromise = this.readFreshSample();
+    this.inFlightSample = samplePromise;
+    try {
+      const sample = await samplePromise;
+      this.cachedSample = sample;
+      return sample;
+    } finally {
+      if (this.inFlightSample === samplePromise) {
+        this.inFlightSample = undefined;
+      }
+    }
+  }
+
+  private async readFreshSample(): Promise<IControllerSystemMetrics> {
+    return normalizeSystemMetrics(this.now(), await this.readSourceMetrics());
+  }
+
+  private async readSourceMetrics(): Promise<IRawSystemMetrics> {
+    const [cpuResult, memoryResult, networkResult] = await Promise.all([
+      this.readCpu(),
+      this.readMemory(),
+      this.readNetwork(),
+    ]);
+    return {
+      ...(cpuResult
+        ? { cpuUsagePercent: cpuResult.currentLoad }
+        : {}),
+      ...(memoryResult
+        ? {
+            memoryUsedBytes: memoryResult.active,
+            memoryTotalBytes: memoryResult.total,
+          }
+        : {}),
+      ...(networkResult
+        ? { networkStats: networkResult }
+        : {}),
+    };
+  }
+
+  private async readCpu(): Promise<{ currentLoad: number } | undefined> {
+    let sourceRead = this.inFlightCpuRead;
+    if (!sourceRead) {
+      sourceRead = Promise.resolve().then(() => this.source.currentLoad());
+      this.inFlightCpuRead = sourceRead;
+      const clear = (): void => {
+        if (this.inFlightCpuRead === sourceRead) this.inFlightCpuRead = undefined;
+      };
+      void sourceRead.then(clear, clear);
+    }
+    return this.withTimeout(sourceRead);
+  }
+
+  private async readMemory(): Promise<{ active: number; total: number } | undefined> {
+    let sourceRead = this.inFlightMemoryRead;
+    if (!sourceRead) {
+      sourceRead = Promise.resolve().then(() => this.source.mem());
+      this.inFlightMemoryRead = sourceRead;
+      const clear = (): void => {
+        if (this.inFlightMemoryRead === sourceRead) this.inFlightMemoryRead = undefined;
+      };
+      void sourceRead.then(clear, clear);
+    }
+    return this.withTimeout(sourceRead);
+  }
+
+  private async readNetwork(): Promise<Array<{ rx_sec: number; tx_sec: number }> | undefined> {
+    let sourceRead = this.inFlightNetworkRead;
+    if (!sourceRead) {
+      sourceRead = Promise.resolve().then(() => this.readNetworkStats());
+      this.inFlightNetworkRead = sourceRead;
+      const clear = (): void => {
+        if (this.inFlightNetworkRead === sourceRead) this.inFlightNetworkRead = undefined;
+      };
+      void sourceRead.then(clear, clear);
+    }
+    return this.withTimeout(sourceRead);
+  }
+
+  private async withTimeout<T>(sourceReadArg: Promise<T>): Promise<T | undefined> {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const timedOut = Symbol('systemMetricsTimeout');
+    try {
+      const result = await Promise.race([
+        sourceReadArg,
+        new Promise<typeof timedOut>((resolve) => {
+          timeout = setTimeout(() => resolve(timedOut), this.sampleTimeoutMs);
+        }),
+      ]);
+      return result === timedOut ? undefined : result;
+    } catch {
+      return undefined;
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+  }
+
+  private async readNetworkStats(): Promise<Array<{ rx_sec: number; tx_sec: number }>> {
+    const interfaces = await this.source.networkInterfaces();
+    const interfaceNames = [...new Set(
+      interfaces
+        .filter((networkInterface) => !networkInterface.virtual && networkInterface.iface.length > 0)
+        .map((networkInterface) => networkInterface.iface),
+    )].slice(0, 128);
+    if (interfaceNames.length === 0) return [];
+    return this.source.networkStats(interfaceNames.join(','));
+  }
+}