@hienlh/ppm 0.23.5 → 0.23.7

package/src/shared/prompt-cache-idle.ts

@@ -0,0 +1,197 @@
+/**
+ * Whether a session has sat idle long enough that its prompt cache is gone.
+ *
+ * The cost of a turn is dominated by the replayed transcript, and that replay is cheap only
+ * while the prefix behind it is still cached (see `turn-usage.ts`). The cache is the one
+ * part of that with a clock on it: it lapses on its own, silently, some time after the last
+ * turn — so the first message of the next morning costs several times what the last message
+ * of the night before did, for no reason visible in the conversation.
+ *
+ * `TurnCostWarning` reports that after the fact, on the turn that paid. This says it
+ * *before*, while the user can still decide whether to carry on in this chat or start a
+ * cheaper one. Pure and shared so the threshold is the same one the warning already uses.
+ */
+
+import { PREFIX_WARN_TOKENS } from "./turn-usage.ts";
+
+/**
+ * What the server knows about a session's cache.
+ *
+ * `ttlMs` alone is the state of a session that has not completed a turn yet — it is a
+ * property of the install, not of the conversation, and sending it early is what lets a
+ * long-lived tab arm this notice from its own turns without waiting for a reconnect.
+ */
+export interface PromptCacheState {
+  /** This install's cache lifetime: an hour on a subscription, five minutes on an API key. */
+  ttlMs: number;
+  /** When the last turn completed — the moment the cache was last written. */
+  lastTurnEndedAt?: number;
+  /**
+   * Cached prefix *billed* on the last turn — a running session total, not a transcript size.
+   *
+   * The SDK sums `modelUsage` across a streaming session, so a long chat reports tens of
+   * millions against a context window of one. It is a usable floor for "has this session
+   * cached anything worth losing" and nothing more; never show it as a number.
+   */
+  billedPrefixTokens?: number;
+  /**
+   * Context the last turn actually held — the figure that may be displayed.
+   *
+   * Measured from one API call's own `usage` rather than summed (see
+   * `TurnUsage.contextTokens`). Absent for a turn recorded before PPM measured this, so the
+   * notice has to read correctly without it.
+   */
+  contextTokens?: number;
+  /**
+   * When this session was compacted, if it has been since its last cache write.
+   *
+   * A compaction replaces the conversation with a summary, so the cached prefix no longer
+   * matches anything that will be sent — the cache is gone regardless of how recently it was
+   * written. Cleared again by the first API call after the boundary, which caches the new
+   * prefix; it therefore only survives a compaction that nothing followed, which is exactly
+   * the `/compact` the user is about to type into.
+   */
+  compactedAt?: number;
+}
+
+/** Why a session's cache is gone. */
+export type ColdReason = "expired" | "compacted";
+
+export interface IdleCacheNotice {
+  /** How long since the last turn, or since the compaction, for the wording. */
+  idleMs: number;
+  reason: ColdReason;
+  /**
+   * Transcript that the next message re-sends, when PPM measured it.
+   *
+   * Never set for a compaction: what will be re-cached then is the summary the compaction
+   * produced, which no API call has reported a size for yet. Claude Code hardcodes the same
+   * `undefined` for that branch.
+   */
+  contextTokens?: number;
+}
+
+/**
+ * The notice to show, or null for nothing worth saying.
+ *
+ * Silent in three cases, all of them deliberate. Before the TTL, because the cache really is
+ * still warm and a countdown to a cost that has not happened is just noise. Below
+ * `PREFIX_WARN_TOKENS`, because a session that has never billed even that much has nothing
+ * worth warning about — the same floor the after-the-fact warning uses, so the two cannot
+ * disagree about what is worth mentioning. And with no state at all, because "PPM has not
+ * measured this" and "this session has nothing cached" must not be reported as the same thing.
+ */
+export function idleCacheNotice(
+  state: PromptCacheState | null | undefined,
+  now: number,
+): IdleCacheNotice | null {
+  const status = promptCacheStatus(state, now);
+  if (status.kind !== "cold") return null;
+  return {
+    idleMs: status.idleMs,
+    reason: status.reason,
+    ...(status.contextTokens != null && { contextTokens: status.contextTokens }),
+  };
+}
+
+/**
+ * The cache's clock, for a countdown that is on screen the whole time.
+ *
+ * Same three gates as the notice, deliberately: a chip that turns red at the hour while no
+ * banner appears — or the reverse — asks the user to reconcile two readings of one fact.
+ * `unknown` means PPM has not measured this session, which must render as nothing rather
+ * than as a full or empty timer.
+ */
+export type PromptCacheStatus =
+  | { kind: "unknown" }
+  | { kind: "warm"; remainingMs: number }
+  | { kind: "cold"; reason: ColdReason; idleMs: number; contextTokens?: number };
+
+export function promptCacheStatus(
+  state: PromptCacheState | null | undefined,
+  now: number,
+): PromptCacheStatus {
+  if (!state) return { kind: "unknown" };
+
+  // Before every other question, including whether anything has been measured at all. A
+  // compaction does not make the cache *stale*, it makes it inapplicable — the prefix it
+  // holds is not the conversation any more — so a turn that finished ten seconds ago is
+  // still cold. Ordered exactly as Claude Code orders it, and it also settles the floor
+  // below: a session large enough to have been compacted is never a trivial one.
+  if (state.compactedAt != null) {
+    return { kind: "cold", reason: "compacted", idleMs: Math.max(0, now - state.compactedAt) };
+  }
+
+  // No completed turn means nothing has been cached, so there is nothing to lose yet.
+  if (state.lastTurnEndedAt == null || state.billedPrefixTokens == null) return { kind: "unknown" };
+  if (state.billedPrefixTokens < PREFIX_WARN_TOKENS) return { kind: "unknown" };
+
+  const idleMs = now - state.lastTurnEndedAt;
+  // A clock that disagrees between server and browser can make this negative; a turn that
+  // just finished is the warmest case there is, so it reads as "not idle" either way.
+  if (idleMs < state.ttlMs) {
+    // Clamped, so a skewed clock shows a full window rather than one longer than the TTL.
+    return { kind: "warm", remainingMs: Math.min(state.ttlMs, state.ttlMs - idleMs) };
+  }
+
+  return {
+    kind: "cold",
+    reason: "expired",
+    idleMs,
+    ...(state.contextTokens != null && { contextTokens: state.contextTokens }),
+  };
+}
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+
+/**
+ * How long the session has been idle, at the coarsest unit that still says something.
+ *
+ * Minutes are dropped past a day: "2d 7h 13m" is three figures to answer "is this stale",
+ * which is the only question being asked.
+ */
+export function formatIdleDuration(ms: number): string {
+  if (ms >= DAY_MS) {
+    const days = Math.floor(ms / DAY_MS);
+    const hours = Math.floor((ms % DAY_MS) / HOUR_MS);
+    return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+  }
+  if (ms >= HOUR_MS) {
+    const hours = Math.floor(ms / HOUR_MS);
+    const minutes = Math.floor((ms % HOUR_MS) / MINUTE_MS);
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+  return `${Math.max(1, Math.floor(ms / MINUTE_MS))}m`;
+}
+
+/**
+ * Time left on the cache, for the composer's countdown chip.
+ *
+ * Rounded **up**, so a fresh turn reads the install's whole window (`60m`, not `59m`) and the
+ * last partial minute reads `1m` rather than `0m` — a zero here would say expired while the
+ * cache is still warm, which is the one reading the chip must never give.
+ *
+ * Minutes throughout, with no hours branch: the longest window PPM has is the subscription's
+ * hour, so the only thing an hours branch could ever render is the full window as `1h` — one
+ * more unit for the eye to parse, in the single case the chip is least interesting.
+ */
+export function formatCacheCountdown(ms: number): string {
+  return `${Math.max(1, Math.ceil(ms / MINUTE_MS))}m`;
+}
+
+/**
+ * A measured context size, at the precision the decision needs.
+ *
+ * Whole thousands: the user is deciding whether to carry on in this chat or start a fresh
+ * one, and no part of that turns on the difference between 58.7k and 59k.
+ */
+export function formatContextTokens(tokens: number): string {
+  if (tokens >= 1_000_000) {
+    const millions = tokens / 1_000_000;
+    return `${millions >= 10 ? Math.round(millions) : millions.toFixed(1)}M`;
+  }
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}k`;
+  return `${tokens}`;
+}

package/src/shared/turn-usage.ts

@@ -46,6 +46,36 @@ export interface TurnUsage {
    */
   accountId?: string;
   accountLabel?: string;
+  /**
+   * Live context held at the end of the turn — what the next message actually replays.
+   *
+   * Not derivable from anything else on this type. Every other field here is summed out of
+   * the result's `modelUsage`, which the SDK accumulates across a streaming session and
+   * across subagents: one measured session reported 55.9M prefix tokens against a 200k
+   * window, and per-turn deltas fare no better (one turn's delta was 4.2M — twenty-one
+   * windows — because twenty subagents each replayed their own prefix into the same sum).
+   *
+   * This comes instead from the `usage` on the turn's last top-level assistant message,
+   * which is one API call's own input side and so is a real context size. Absent when no
+   * such message carried usage; never substitute a summed figure for it.
+   */
+  contextTokens?: number;
+  /**
+   * Cache window the API reported for this turn, when it reported one.
+   *
+   * Outranks the provider's credential-shaped guess wherever both exist — see
+   * `messageCacheTtl`. Absent on a turn that only read the cache, and on every turn recorded
+   * before PPM read this field.
+   */
+  cacheTtlMs?: number;
+  /**
+   * When a compaction invalidated this session's cache, if one did and nothing re-cached after.
+   *
+   * Not a timestamp of "the last compaction" — the provider clears it on the next API call,
+   * so an auto-compact mid-turn never reaches here. What survives is a compaction the turn
+   * ended on, which is the case where the user's next message pays to rebuild the prefix.
+   */
+  compactedAt?: number;
 }
 
 /** Total prefix replayed to the API this turn, cached or not. */
@@ -66,7 +96,7 @@ export function uncachedPrefixTokens(u: TurnUsage): number {
  */
 export function buildTurnUsage(
   modelUsage: Record<string, ModelUsageLike> | undefined,
-  opts: { coldReason?: string; accountId?: string; accountLabel?: string } = {},
+  opts: { coldReason?: string; accountId?: string; accountLabel?: string; contextTokens?: number; cacheTtlMs?: number; compactedAt?: number } = {},
 ): TurnUsage | undefined {
   if (!modelUsage) return undefined;
   const entries = Object.entries(modelUsage);
@@ -113,9 +143,63 @@ export function buildTurnUsage(
     ...(opts.coldReason && { coldReason: opts.coldReason }),
     ...(opts.accountId && { accountId: opts.accountId }),
     ...(opts.accountLabel && { accountLabel: opts.accountLabel }),
+    ...(opts.contextTokens != null && { contextTokens: opts.contextTokens }),
+    ...(opts.cacheTtlMs != null && { cacheTtlMs: opts.cacheTtlMs }),
+    ...(opts.compactedAt != null && { compactedAt: opts.compactedAt }),
   };
 }
 
+/**
+ * Context size carried by one assistant message's `usage`, or undefined if it carried none.
+ *
+ * The input side of a single API call: what the model was actually given, whether it arrived
+ * fresh or out of the cache. Output tokens are excluded — they are not in the context the
+ * *next* call replays until they have been written back as a message, and counting them here
+ * would inflate every turn by its own answer.
+ */
+export function messageContextTokens(usage: unknown): number | undefined {
+  if (!usage || typeof usage !== "object") return undefined;
+  const u = usage as Record<string, unknown>;
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  const total = num(u.input_tokens) + num(u.cache_read_input_tokens) + num(u.cache_creation_input_tokens);
+  // Zero is not a context, it is a frame that carried no input side — a usage object with
+  // only output tokens, say. Returning it would render as "re-sends about 0 tokens" on a
+  // full session. Matches Claude Code's own reader, which likewise sums all three fields
+  // without requiring any one of them and rejects a zero total.
+  return total > 0 ? total : undefined;
+}
+
+/** Which prompt-cache window the API wrote this turn's prefix into. */
+export type PromptCacheTtl = "1h" | "5m";
+
+/**
+ * The cache lifetime the API itself reports, or undefined when it reported none.
+ *
+ * PPM otherwise *infers* this from the credential — an `sk-ant-oat` token means a
+ * subscription and therefore an hour, anything else five minutes — which is a guess about
+ * billing made from the shape of a string. It is wrong for a proxy, for a custom `base_url`,
+ * and for a subscription past its usage limits, and being wrong is not cosmetic: the
+ * countdown and the idle banner both measure against this, so a session whose cache really
+ * lives an hour is declared cold at minute five.
+ *
+ * `usage.cache_creation` answers it outright. Mirrors Claude Code's own reader, including
+ * the order: a prefix written into both windows is reported as the longer one, because that
+ * is the one still standing. Returns the discriminant rather than milliseconds so this stays
+ * free of the server's constants — `shared/` is imported by the browser bundle.
+ */
+export function messageCacheTtl(usage: unknown): PromptCacheTtl | undefined {
+  if (!usage || typeof usage !== "object") return undefined;
+  const cc = (usage as { cache_creation?: unknown }).cache_creation;
+  if (!cc || typeof cc !== "object") return undefined;
+  const c = cc as Record<string, unknown>;
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  if (num(c.ephemeral_1h_input_tokens) > 0) return "1h";
+  if (num(c.ephemeral_5m_input_tokens) > 0) return "5m";
+  // A turn that only *read* the cache writes nothing, so it names no window. That is silence,
+  // not five minutes: answering the short one here would expire a warm hour-long cache.
+  return undefined;
+}
+
 /**
  * A prefix smaller than this is cheap however it is billed, so a poor hit rate on it is not
  * worth interrupting the user over. Short sessions legitimately start cold.

package/src/shared/usage-extra.ts

@@ -84,9 +84,28 @@ export function parseCodexResetCredits(raw: unknown): ResetCredits | undefined {
     available: available.length,
     ...(typeof next?.expiresAt === "number" ? { nextExpiresAt: new Date(next.expiresAt * 1000).toISOString() } : {}),
     ...(typeof next?.title === "string" ? { title: next.title } : {}),
+    ...(typeof next?.id === "string" ? { nextCreditId: next.id } : {}),
   };
 }
 
+/**
+ * Whether a limit has actually been reached — at 100% of a window, as the card rounds it.
+ *
+ * The one rule both the "Use reset" button and the server's refusal follow, so the button can
+ * never offer what the server would turn down. Reached, not approaching: spending a reset at
+ * 90% throws away the 10% left *and* moves the weekly reset date (OpenAI: the next weekly reset
+ * is counted from when you continue, and the original one is not also granted).
+ */
+export function usageLimitReached(u: { session?: { utilization: number }; weekly?: { utilization: number } }): boolean {
+  const atCap = (util?: number) => Math.round((util ?? 0) * 100) >= 100;
+  return atCap(u.session?.utilization) || atCap(u.weekly?.utilization);
+}
+
+/** A reset may be offered: a limit is reached and a credit is left to spend on it. */
+export function canUseResetCredit(u: { session?: { utilization: number }; weekly?: { utilization: number }; resetCredits?: ResetCredits }): boolean {
+  return usageLimitReached(u) && (u.resetCredits?.available ?? 0) > 0;
+}
+
 /** The extra fields of a `UsageInfo`, as the JSON column holds them — null when there are none. */
 export function serializeUsageExtra(u: { weeklyScoped?: ScopedLimitBucket[]; resetCredits?: ResetCredits }): string | null {
   const extra: UsageExtra = {};

package/src/types/chat.ts

@@ -230,6 +230,8 @@ export interface ResetCredits {
   nextExpiresAt?: string;
   /** What the soonest one resets, as Codex words it ("Full reset (Weekly + 5 hr)"). */
   title?: string;
+  /** Codex's opaque id of that soonest-expiring credit — the one "Use reset" spends. */
+  nextCreditId?: string;
 }
 
 /** Result subtype from SDK ResultMessage */
@@ -280,4 +282,31 @@ export interface ChatMessage {
   sdkUuid?: string;
   /** Token split for the turn that produced this message; drives the cost warning. */
   usage?: import("../shared/turn-usage").TurnUsage;
+  /**
+   * Set only on the compact-summary message that opens a post-compaction segment,
+   * so the divider above it can say what the compaction cost and saved.
+   */
+  compaction?: CompactionInfo;
+}
+
+/**
+ * What one compaction did, read back from the `compact_boundary` record Claude Code
+ * writes into the transcript.
+ *
+ * Taken from the file rather than from the live `compact_boundary` event because the
+ * figure has to survive a reload: the turn that compacts ends by refetching history,
+ * so a notice that existed only in WebSocket state would vanish seconds after it
+ * appeared. The event carries the same numbers and is deliberately not plumbed.
+ */
+export interface CompactionInfo {
+  /** `auto` when the context window forced it, `manual` when the user ran /compact. */
+  trigger: "manual" | "auto";
+  /** Transcript size going in. */
+  preTokens: number;
+  /** Size of the summary that replaced it. */
+  postTokens: number;
+  /** `preTokens - postTokens` — this compaction alone, not the session's running total. */
+  savedTokens: number;
+  /** How long the compaction took, when the record says. */
+  durationMs?: number;
 }

package/src/types/config.ts

@@ -44,6 +44,14 @@ export interface PpmConfig {
  * `zoneID`/`accountID` are pinned at setup and re-checked on every reuse.
  */
 export interface TunnelConfig {
+  /**
+   * Master switch for the public tunnel. `false` means the supervisor spawns no
+   * cloudflared at all, whatever `mode` says — a machine reached over a LAN, a
+   * VPN or Tailscale gains nothing from a public URL and pays for it in
+   * exposure. Absent in rows written before this switch existed, so every
+   * reader must default it to `true`: the tunnel used to be unconditional.
+   */
+  enabled: boolean;
   mode: "quick" | "named";
   namedTunnelName?: string;
   namedTunnelHostname?: string;
@@ -176,6 +184,7 @@ export const DEFAULT_CONFIG: PpmConfig = {
     debounce_ms: 2000,
   },
   tunnel: {
+    enabled: true,
     mode: "quick",
   },
 };
@@ -348,6 +357,11 @@ export function sanitizeConfig(config: PpmConfig): boolean {
       (config.tunnel.mode !== "quick" && config.tunnel.mode !== "named")) {
     config.tunnel = structuredClone(DEFAULT_CONFIG.tunnel);
     dirty = true;
+  } else if (typeof config.tunnel.enabled !== "boolean") {
+    // Written before the master switch existed, when the tunnel was
+    // unconditional — so an absent flag must read as on, never off.
+    config.tunnel.enabled = true;
+    dirty = true;
   }
 
   return dirty;

package/src/types/git.ts

@@ -21,6 +21,47 @@ export interface GitBranch {
   remotes: string[];
 }
 
+/**
+ * One checkout target for the branch picker: a local branch, a remote-tracking
+ * branch or a tag, together with the commit it points at.
+ *
+ * Separate from `GitBranch` because that shape is what the graph draws and it
+ * carries no commit metadata — the picker needs an author, a subject and a date
+ * per row, and it needs tags, which `branches()` never returns.
+ */
+export interface GitRef {
+  /** Full ref name: `refs/heads/main`, `refs/remotes/origin/main`, `refs/tags/v1`. */
+  refName: string;
+  /** Short name, as a user reads it and as git checks it out by: `main`, `origin/main`, `v1`. */
+  name: string;
+  type: "branch" | "remote" | "tag";
+  /** True for the one local branch HEAD is on. */
+  current: boolean;
+  /** The commit this ref resolves to — dereferenced, so an annotated tag names its commit. */
+  hash: string;
+  shortHash: string;
+  subject: string;
+  author: string;
+  /** ISO 8601 commit date. */
+  date: string;
+  /** Upstream ref short name (`origin/main`), or null. Local branches only. */
+  upstream: string | null;
+  /** Commits ahead of / behind `upstream`; both 0 when there is none. */
+  ahead: number;
+  behind: number;
+  /** An upstream is configured but no longer exists on the remote. */
+  gone: boolean;
+}
+
+/**
+ * How `git checkout` is asked to move HEAD.
+ *
+ * `track` exists because a remote-tracking ref is not a branch: plain
+ * `git checkout origin/foo` lands on a detached HEAD, and `-t` is what creates
+ * the local `foo` that follows it.
+ */
+export type CheckoutMode = "checkout" | "detach" | "track";
+
 export interface GitStatus {
   current: string | null;
   /** Commits ahead of the upstream branch. */

package/src/types/system-hardware.ts

@@ -0,0 +1,137 @@
+/** Static hardware facts for the Performance page — everything that does not change
+ *  tick to tick, served once by GET /api/system/hardware instead of riding every 2 s
+ *  snapshot over a tunnel. The client refetches when a snapshot names a device id it
+ *  does not know (a USB disk plugged in, an interface created). Types + constants
+ *  only. Import RELATIVELY — the "@" alias points at src/web. */
+import type { GpuInfo, MetricsPlatform } from "./system-metrics.ts";
+
+export type DiskKind = "hdd" | "ssd" | "nvme" | "emmc" | "sd" | "optical" | "thumb" | "unknown";
+
+/** One place a partition is mounted. A partition can have several: a btrfs
+ *  subvolume layout mounts the same device at `/`, `/home` and `/var/log`. */
+export interface PartitionMount {
+  mountPoint: string;
+  filesystem: string;
+  /** From `statfs` on the mount, not from the partition's size — metadata,
+   *  root-reserved blocks and a shared subvolume pool all make the two differ.
+   *  Both absent when statfs refused; a filesystem we could not read is not an
+   *  empty one. */
+  usedBytes?: number;
+  totalBytes?: number;
+}
+
+export interface PartitionInfo {
+  /** Kernel name, e.g. "sda1". */
+  id: string;
+  devicePath: string;
+  /** What the partition table says, which is the number that never changes. */
+  sizeBytes: number;
+  /** udev's `ID_FS_TYPE`, so it is known even for a partition nothing mounted. */
+  filesystem?: string;
+  /** Empty for a partition that is not mounted anywhere. */
+  mounts: PartitionMount[];
+}
+
+export interface DiskInfo {
+  /** /sys/block name — the key `DiskMetrics.id` uses. */
+  id: string;
+  /** Vendor + model as the drive reports them; absent when it reports neither. */
+  model?: string;
+  kind: DiskKind;
+  capacityBytes: number;
+  /** Holds the root filesystem (through partitions, LUKS or LVM). */
+  systemDisk: boolean;
+  removable: boolean;
+  serial?: string;
+  wwn?: string;
+  rotationRpm?: number;
+  /** Absent on a platform with no partition support yet; empty on a disk with no
+   *  partition table (a whole-device filesystem, an unformatted drive). */
+  partitions?: PartitionInfo[];
+}
+
+/** Mission Center's interface kinds. It classifies by name prefix because its
+ *  NetworkManager type read always fails; PPM uses sysfs first and the same
+ *  prefixes only as the fallback. */
+export type NicKind =
+  | "wired" | "wireless" | "bluetooth" | "bridge" | "docker" | "infiniband"
+  | "multipass" | "virtual" | "vpn" | "other";
+
+export interface NicInfo {
+  /** Interface name — the key `NicMetrics.id` uses. */
+  id: string;
+  kind: NicKind;
+  /** Adapter name from the PCI/USB database ("RTL8125 2.5GbE Controller"). */
+  deviceName?: string;
+  driver?: string;
+  /** Hardware address, absent for interfaces without one (tun, wireguard). */
+  mac?: string;
+  ipv4: string[];
+  ipv6: string[];
+}
+
+/** Static CPU facts — Mission Center's CPU page header and its bottom grid. */
+export interface CpuInfo {
+  /** Marketing name, e.g. "12th Gen Intel(R) Core(TM) i9-12900K". */
+  name: string;
+  /** Populated sockets. */
+  sockets: number;
+  /** Physical cores across all sockets, and hardware threads. On a hybrid part
+   *  (Intel P+E) the physical count is what the kernel reports per socket. */
+  physicalCores: number;
+  logicalCores: number;
+  /** Nominal clock and the highest the driver will ask for, MHz. */
+  baseMHz?: number;
+  maxMHz?: number;
+  /** "Intel VT-x" / "AMD-V", absent when the flag is missing (or hidden in a VM). */
+  virtualization?: string;
+  /** True when this kernel is itself running virtualised. */
+  isVirtualMachine: boolean;
+  /** Summed over DISTINCT caches, bytes. L1 combines data and instruction, as
+   *  Mission Center does. Absent when sysfs exposes no cache topology. */
+  l1CacheBytes?: number;
+  l2CacheBytes?: number;
+  l3CacheBytes?: number;
+  /** cpufreq's driver, governor and energy-performance preference. */
+  freqDriver?: string;
+  freqGovernor?: string;
+  powerPreference?: string;
+}
+
+/** One populated memory slot, from the SMBIOS table udev already decoded. */
+export interface MemoryDeviceInfo {
+  /** Slot name as the board labels it, e.g. "DDR4-A1". */
+  locator: string;
+  bankLocator?: string;
+  sizeBytes: number;
+  /** "DIMM", "SODIMM", … */
+  formFactor?: string;
+  /** "DDR4", "DDR5", … */
+  ramType?: string;
+  /** Configured transfer rate, MT/s. */
+  speedMts?: number;
+  manufacturer?: string;
+  rank?: number;
+}
+
+export interface MemoryInfo {
+  /** Populated slots. Empty when the firmware table is unreadable — the UI then
+   *  shows the totals only, as Mission Center does inside a VM. */
+  devices: MemoryDeviceInfo[];
+  /** Slots the board has in total, when the firmware says. */
+  slotsTotal?: number;
+  /** Largest configuration the board accepts, bytes. */
+  maxCapacityBytes?: number;
+}
+
+export interface HardwareInventory {
+  platform: MetricsPlatform;
+  /** Epoch ms the inventory was read. */
+  ts: number;
+  disks: DiskInfo[];
+  nics: NicInfo[];
+  gpus: GpuInfo[];
+  /** Absent where the host exposes no CPU topology (never on Linux). */
+  cpu?: CpuInfo;
+  memory?: MemoryInfo;
+}