@omercnet/paseo-top 0.0.1-alpha → 0.0.1-next.250.1

package/OVERVIEW.md

@@ -4,7 +4,7 @@ Usage always describes one host. With several hosts connected, the footer follow
 
 **Load by session** adds up the CPU and memory of everything an agent started, not only the agent process. A build, test run or dev server launched by a tool counts toward the agent that launched it. Each row shows the agent and workspace names you gave them, the busiest command in its tree, cores and memory in use, and opens the agent when pressed. A session is flagged with a flame, and counted in the footer, when it holds one busy core for 30 seconds or a quarter of the host's memory. Everything not listed is shown on one "Everything else" line.
 
-How processes are matched to agents: Paseo gives every agent session an identifier in its environment, and everything the session starts inherits it. Top reads only that identifier from each process, never the rest of the environment. A process whose environment was cleared by a tool is charged to the nearest ancestor that has one. Only agents that belong to the host you are viewing are listed; processes of agents that belong to other daemons on the same machine are counted under "Everything else", together with processes of no agent and sessions beyond the first ten. Per-session load needs Linux and only sees processes owned by the daemon's user. Containers run outside the agent's process tree and show as unattributed.
+How processes are matched to agents: Paseo gives every agent session an identifier in its environment, and everything the session starts inherits it. On every scan Top reads each process's environment into memory, keeps only that identifier and drops the rest at once; nothing else from it is stored, logged or sent anywhere. A process whose environment cannot be read, such as one owned by another user, cannot be tagged. A process with no identifier is charged to the nearest ancestor that has one, since tools often clear it. Only agents that belong to the host you are viewing are listed; processes of agents that belong to other daemons on the same machine are counted under "Everything else", together with untagged processes and sessions beyond the first ten. Per-session load needs Linux. The scan covers every process `/proc` lists, so other users' processes are counted too, under "Everything else". Containers run outside the agent's process tree and show as unattributed.
 
 What the numbers are and are not: load is sampled every ten seconds, so a process that starts and exits between two scans is never seen, and one that is still running is charged for the CPU it used since it started. A session is flagged only when it has held a full core across three scans in a row, so a single burst does not flag it. Memory is each process's resident memory added up, so memory shared between processes of one agent is counted more than once, and the quarter-of-memory rule compares against the machine's memory, not a container's limit. Sessions plus "Everything else" cover the processes that were scanned, not the whole host: kernel time, finished processes and the page cache are outside them.
 

package/README.md

@@ -2,6 +2,10 @@
 
 A Paseo plugin that shows CPU, memory, disk and disk I/O of a host in the sidebar footer, and which agent sessions are responsible. See [OVERVIEW.md](OVERVIEW.md) for behavior.
 
+## Screenshots
+
+![Top screen with host resource gauges and per-session load](https://raw.githubusercontent.com/omercnet/paseo-plugins/pr-assets-top/top-screen.jpg)
+
 ## Develop
 
 ```sh

package/client/footer.tsx

@@ -2,19 +2,26 @@ import type { PluginSidebarItemProps } from "@getpaseo/plugin/client";
 import { Icon } from "@getpaseo/plugin/client/react-native";
 import { SidebarRow } from "@getpaseo/plugin/client/ui";
 import { Text, View } from "react-native";
-import { formatPercent, formatRate, levelColor } from "./format";
+import { formatPercent, formatRate, type Level, levelColor, loadLevel } from "./format";
 import { SCREEN_ID, useUsage } from "./usage";
 
+const LEVEL_NAME: Record<Level, string> = { ok: "", warn: ", high", hot: ", critical" };
+
+/** What a screen reader says: the reading in words, with the level spelled out, not just coloured. */
+function metricLabel(name: string, text: string, level: Level): string {
+  return text === "--" ? `${name} unavailable` : `${name} ${text}${LEVEL_NAME[level]}`;
+}
+
 export function TopFooter({ theme, host, currentScreen, openScreen }: PluginSidebarItemProps) {
   const usage = useUsage(host.id);
   const heavy = usage.data?.sessions?.filter((session) => session.heavy).length ?? 0;
   const metrics =
     usage.data &&
     ([
-      ["Cpu", formatPercent(usage.data.cpu), usage.data.cpu],
-      ["MemoryStick", formatPercent(usage.data.memory), usage.data.memory],
-      ["HardDrive", formatPercent(usage.data.disk), usage.data.disk],
-      ["Gauge", formatRate(usage.data.io), null],
+      ["Cpu", "CPU", formatPercent(usage.data.cpu), usage.data.cpu],
+      ["MemoryStick", "Memory", formatPercent(usage.data.memory), usage.data.memory],
+      ["HardDrive", "Disk", formatPercent(usage.data.disk), usage.data.disk],
+      ["Gauge", "Disk I/O", formatRate(usage.data.io), null],
     ] as const);
 
   return (
@@ -29,15 +36,25 @@ export function TopFooter({ theme, host, currentScreen, openScreen }: PluginSide
             <Text style={{ color: theme.colors.statusDanger, fontSize: 11 }}>unavailable</Text>
           )}
           {heavy > 0 && (
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 2 }}>
+            <View
+              accessible
+              accessibilityLabel={`${heavy} heavy ${heavy === 1 ? "session" : "sessions"}`}
+              style={{ flexDirection: "row", alignItems: "center", gap: 2 }}
+            >
               <Icon name="Flame" size={11} color={theme.colors.statusDanger} />
               <Text style={{ color: theme.colors.statusDanger, fontSize: 11 }}>{heavy}</Text>
             </View>
           )}
-          {metrics?.map(([icon, text, percent]) => {
+          {metrics?.map(([icon, name, text, percent]) => {
             const color = levelColor(theme, percent);
+            const level = loadLevel(percent);
             return (
-              <View key={icon} style={{ flexDirection: "row", alignItems: "center", gap: 2 }}>
+              <View
+                key={icon}
+                accessible
+                accessibilityLabel={metricLabel(name, text, level)}
+                style={{ flexDirection: "row", alignItems: "center", gap: 2 }}
+              >
                 <Icon name={icon} size={11} color={color} />
                 <Text
                   numberOfLines={1}

package/client/gauge.tsx

@@ -31,12 +31,14 @@ export function Dial({ theme, size, icon, label, value, text }: DialProps) {
   const needleLength = radius * 0.72;
   const degrees = useRef(new Animated.Value(needleDegrees(value))).current;
   useEffect(() => {
-    Animated.timing(degrees, {
+    const animation = Animated.timing(degrees, {
       toValue: needleDegrees(value),
       duration: 700,
       easing: Easing.out(Easing.cubic),
       useNativeDriver: false,
-    }).start();
+    });
+    animation.start();
+    return () => animation.stop();
   }, [degrees, value]);
   const rotate = degrees.interpolate({
     inputRange: [-SWEEP / 2, SWEEP / 2],

package/client/screen.tsx

@@ -68,6 +68,10 @@ export function TopScreen({ theme, layout, host, navigation }: PluginScreenProps
           {host.label}
         </Text>
         <View
+          accessible
+          accessibilityLabel={
+            usage.isError ? "Usage unavailable" : usage.data ? "Usage live" : "Usage loading"
+          }
           style={{
             width: 8,
             height: 8,

package/index.server.ts

@@ -11,5 +11,8 @@ export default function contribute(server: PluginServerContext) {
     if (!usage.sessions) return usage;
     return { ...usage, ...(await ownSessions(paseo, usage.sessions, usage.other)) };
   });
-  return sampler.stop;
+  return () => {
+    sampler.stop();
+    ownSessions.stop();
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-top",
-  "version": "0.0.1-alpha",
+  "version": "0.0.1-next.250.1",
   "type": "module",
   "description": "A Paseo plugin that shows host CPU, memory and disk usage in the sidebar footer.",
   "license": "MIT",

package/paseo-plugin.json

@@ -1,5 +1,8 @@
 {
   "id": "top",
   "description": "CPU, memory and disk usage of the selected host in the sidebar footer.",
+  "media": [
+    "https://raw.githubusercontent.com/omercnet/paseo-plugins/pr-assets-top/top-screen.jpg"
+  ],
   "requirements": { "paseo": "^0.11.0" }
 }

package/server/names.ts

@@ -7,6 +7,8 @@ const FULL_REFRESH_MS = 30_000;
 const EARLY_REFRESH_MS = 5000;
 /** Only the first ever fetch is waited for, and not forever. */
 const FIRST_FETCH_TIMEOUT_MS = 3000;
+/** A read that has not settled by now is abandoned and cancelled, so a hung daemon cannot block later reads. */
+const REFRESH_LIFETIME_MS = 20_000;
 const PAGE_SIZE = 200;
 export const MAX_PAGES = 25;
 export const MAX_SESSIONS = 10;
@@ -26,12 +28,23 @@ interface Page<T> {
   pageInfo: { hasMore: boolean; nextCursor: string | null };
 }
 
-/** The daemon pages its lists, and an agent left off the first page must still be recognised. */
-async function collect<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>) {
+/**
+ * The daemon pages its lists, and an agent left off the first page must still be recognised. Aborting
+ * ends the read even when the daemon never answers the page in flight, which is then ignored.
+ */
+async function collect<T>(
+  signal: AbortSignal,
+  fetchPage: (cursor: string | undefined) => Promise<Page<T>>,
+) {
+  const aborted = new Promise<never>((_, reject) => {
+    const cancel = () => reject(new Error("Daemon read cancelled"));
+    if (signal.aborted) cancel();
+    else signal.addEventListener("abort", cancel, { once: true });
+  });
   const entries: T[] = [];
   let cursor: string | undefined;
   for (let page = 0; page < MAX_PAGES; page++) {
-    const result = await fetchPage(cursor);
+    const result = await Promise.race([fetchPage(cursor), aborted]);
     entries.push(...result.entries);
     if (!result.pageInfo.hasMore || !result.pageInfo.nextCursor) break;
     cursor = result.pageInfo.nextCursor;
@@ -40,7 +53,7 @@ async function collect<T>(fetchPage: (cursor: string | undefined) => Promise<Pag
 }
 
 /**
- * The process scan sees every process the daemon's user owns, including agents that belong to other
+ * The process scan sees every readable process /proc lists, including agents that belong to other
  * daemons on the same machine. This keeps only the sessions of agents this daemon knows, names them
  * with the user's own agent and workspace names, and folds everything else into `other` so the
  * numbers still add up to the processes that were scanned.
@@ -48,34 +61,48 @@ async function collect<T>(fetchPage: (cursor: string | undefined) => Promise<Pag
  * The daemon's lists are read in the background and shared between callers, so a slow daemon never
  * holds up the readings. Only the very first read is waited for, for a few seconds at most. Until
  * then, and whenever the lists have never been available, no session can be shown as this host's and
- * all of its load is reported as other load. Once read, a failed refresh keeps the last lists.
+ * all of its load is reported as other load. Once read, a failed refresh keeps the last lists. A read
+ * that outlives `REFRESH_LIFETIME_MS` is cancelled and replaced by the next one, and whatever the
+ * abandoned read later returns is discarded. `stop` cancels the read in flight.
  */
 export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETCH_TIMEOUT_MS) {
   let known: Known | null = null;
   /** Agents confirmed absent from the latest read, so they do not trigger another one. */
   let foreign = new Set<string>();
   let fetchedAt = Number.NEGATIVE_INFINITY;
-  let inflight: Promise<void> | null = null;
+  let inflight: { done: Promise<void>; startedAt: number; abort: AbortController } | null = null;
 
   const refresh = (paseo: PaseoApi, candidates: string[]) => {
-    if (inflight) return inflight;
+    if (inflight && now() - inflight.startedAt >= REFRESH_LIFETIME_MS) {
+      inflight.abort.abort();
+      inflight = null;
+    }
+    if (inflight) return inflight.done;
     fetchedAt = now();
-    inflight = (async () => {
+    const abort = new AbortController();
+    const { signal } = abort;
+    const run = { done: Promise.resolve(), startedAt: fetchedAt, abort };
+    inflight = run;
+    run.done = (async () => {
       try {
         const [agents, workspaces] = await Promise.all([
-          collect((cursor) =>
+          collect(signal, (cursor) =>
             paseo.agents.list({
               filter: { includeArchived: true },
               // Oldest first: an agent's creation time never changes, so paging cannot skip one that
               // is busy and being updated while the pages are read.
               sort: [{ key: "created_at", direction: "asc" }],
               page: { limit: PAGE_SIZE, ...(cursor ? { cursor } : {}) },
+              signal,
             }),
           ),
-          collect((cursor) =>
+          // The SDK's workspace list takes no signal; the abort stops the paging between pages.
+          collect(signal, (cursor) =>
             paseo.workspaces.list({ page: { limit: PAGE_SIZE, ...(cursor ? { cursor } : {}) } }),
           ),
         ]);
+        // An abandoned read must not overwrite what a newer one stored.
+        if (inflight !== run) return;
         const next: Known = {
           agents: new Map(
             agents.map(({ agent }) => [
@@ -91,14 +118,14 @@ export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETC
         foreign = new Set(candidates.filter((id) => !next.agents.has(id)));
       } catch {
         // Keep the previous lists.
+      } finally {
+        if (inflight === run) inflight = null;
       }
-    })().finally(() => {
-      inflight = null;
-    });
-    return inflight;
+    })();
+    return run.done;
   };
 
-  return async (paseo: PaseoApi, sessions: Session[], other: Load) => {
+  const ownership = async (paseo: PaseoApi, sessions: Session[], other: Load) => {
     if (sessions.length === 0) return { sessions, other };
 
     const ids = sessions.map((session) => session.agentId);
@@ -107,7 +134,7 @@ export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETC
     const pending =
       age >= FULL_REFRESH_MS || (unseen && age >= EARLY_REFRESH_MS)
         ? refresh(paseo, ids)
-        : inflight;
+        : inflight?.done;
     if (known === null && pending) {
       await new Promise<void>((resolve) => {
         const timer = setTimeout(resolve, firstFetchTimeoutMs);
@@ -140,4 +167,11 @@ export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETC
     }
     return { sessions: own.slice(0, MAX_SESSIONS), other: rest };
   };
+
+  return Object.assign(ownership, {
+    stop: () => {
+      inflight?.abort.abort();
+      inflight = null;
+    },
+  });
 }

package/server/processes.ts

@@ -68,7 +68,7 @@ export function parseStat(text: string): Stat | null {
   return { comm: text.slice(open + 1, close), ...numbers, rss: Math.max(0, numbers.rss) };
 }
 
-/** Only the agent id is read out of the environment; the rest of it can hold secrets and is dropped. */
+/** The whole environment is read, but only the agent id is kept; the rest can hold secrets and is dropped. */
 export function parseAgentId(environ: string): string | null {
   for (const entry of environ.split("\0")) {
     if (entry.startsWith("PASEO_AGENT_ID=")) return entry.slice("PASEO_AGENT_ID=".length) || null;
@@ -77,34 +77,29 @@ export function parseAgentId(environ: string): string | null {
 }
 
 /**
- * Every process the daemon's user can see. A process's environment never changes after it starts, so
- * it is read once and remembered in `agentIds`; entries for processes that are gone are dropped.
+ * Every process listed under /proc, which includes other users' that are readable. The environment
+ * is read whole but only `PASEO_AGENT_ID` is kept, and it is read again on every scan, because a
+ * process can replace its environment when it execs without changing its pid or start time. A
+ * process whose environment cannot be read (another user's) has no agent.
  */
-export function readProcs(agentIds: Map<string, string | null>, root = "/proc"): ProcInfo[] {
+export function readProcs(root = "/proc"): ProcInfo[] {
   const procs: ProcInfo[] = [];
-  const seen = new Set<string>();
   for (const name of readdirSync(root)) {
     if (!/^\d+$/.test(name)) continue;
     try {
       const stat = parseStat(readFileSync(`${root}/${name}/stat`, "utf8"));
       if (!stat) continue;
-      const key = `${name}:${stat.start}`;
-      seen.add(key);
-      let agentId = agentIds.get(key);
-      if (agentId === undefined) {
-        try {
-          agentId = parseAgentId(readFileSync(`${root}/${name}/environ`, "utf8"));
-        } catch {
-          agentId = null; // another user's process
-        }
-        agentIds.set(key, agentId);
+      let agentId: string | null;
+      try {
+        agentId = parseAgentId(readFileSync(`${root}/${name}/environ`, "utf8"));
+      } catch {
+        agentId = null;
       }
-      procs.push({ key, pid: Number(name), agentId, ...stat });
+      procs.push({ key: `${name}:${stat.start}`, pid: Number(name), agentId, ...stat });
     } catch {
       // The process exited while it was being read.
     }
   }
-  for (const key of agentIds.keys()) if (!seen.has(key)) agentIds.delete(key);
   return procs;
 }
 

package/server/usage.ts

@@ -18,10 +18,11 @@ export function readCpuTimes(cpus: ReadonlyArray<Pick<os.CpuInfo, "times">> = os
   return { idle, total };
 }
 
-/** Busy share between two readings, or null when no time elapsed or the counters went backwards. */
+/** Busy share between two readings, or null when no time elapsed, the counters went backwards or are not numbers. */
 export function cpuPercent(previous: CpuTimes, current: CpuTimes): number | null {
   const total = current.total - previous.total;
   const idle = current.idle - previous.idle;
+  if (!Number.isFinite(total) || !Number.isFinite(idle)) return null;
   if (total <= 0 || idle < 0 || idle > total) return null;
   return (1 - idle / total) * 100;
 }
@@ -35,13 +36,18 @@ export function diskPercent(
     const { blocks, bfree, bavail } = stat(path);
     const used = blocks - bfree;
     const usable = used + bavail;
-    return usable > 0 ? (used / usable) * 100 : null;
+    const percent = (used / usable) * 100;
+    return usable > 0 && Number.isFinite(percent) ? Math.min(100, Math.max(0, percent)) : null;
   } catch {
     return null;
   }
 }
 
-/** Whole-disk bytes read plus written since boot (Linux only); null where /proc is unavailable. */
+/**
+ * Whole-disk bytes read plus written since boot (Linux only). Null where /proc is unavailable, and
+ * when any whole disk has a malformed counter: a partial total would show up as a throughput spike
+ * once the counter reads again.
+ */
 export function readDiskBytes(
   sysBlock = "/sys/block",
   diskstats = "/proc/diskstats",
@@ -52,31 +58,53 @@ export function readDiskBytes(
       readdirSync(sysBlock).filter((name) => !/^(loop|ram|dm-|zram|md)/.test(name)),
     );
     let sectors = 0;
+    let matched = false;
     for (const line of readFileSync(diskstats, "utf8").split("\n")) {
       const fields = line.trim().split(/\s+/);
-      if (disks.has(fields[2] ?? "")) sectors += Number(fields[5]) + Number(fields[9]);
+      if (!disks.has(fields[2] ?? "")) continue;
+      const read = Number(fields[5]);
+      const written = Number(fields[9]);
+      if (!(Number.isFinite(read) && read >= 0 && Number.isFinite(written) && written >= 0)) {
+        return null;
+      }
+      sectors += read + written;
+      matched = true;
     }
-    return sectors * 512;
+    return matched && Number.isFinite(sectors) ? sectors * 512 : null;
   } catch {
     return null;
   }
 }
 
-/** Bytes per second between two readings, or null when the counter is missing or went backwards. */
+/** Bytes per second between two readings, or null when a counter is missing, not finite, or went backwards. */
 export function bytesPerSecond(
   previous: number | null,
   current: number | null,
   elapsedMs: number,
 ): number | null {
-  if (previous === null || current === null || current < previous || elapsedMs <= 0) return null;
-  return ((current - previous) * 1000) / elapsedMs;
+  if (previous === null || current === null) return null;
+  if (!(Number.isFinite(previous) && Number.isFinite(current) && Number.isFinite(elapsedMs))) {
+    return null;
+  }
+  if (current < previous || elapsedMs <= 0) return null;
+  const rate = ((current - previous) * 1000) / elapsedMs;
+  return Number.isFinite(rate) ? rate : null;
+}
+
+/**
+ * Used share of memory, clamped to 0-100; null when the host reports no usable total. Linux reports
+ * reclaimable cache as free, so this is memory programs cannot get back.
+ */
+export function memoryPercent(total = os.totalmem(), free = os.freemem()): number | null {
+  if (!Number.isFinite(total) || !Number.isFinite(free) || total <= 0) return null;
+  return Math.min(100, Math.max(0, (1 - free / total) * 100));
 }
 
 interface SamplerOptions {
   intervalMs?: number;
   readCpu?: () => CpuTimes;
   readIo?: () => number | null;
-  readMemory?: () => number;
+  readMemory?: () => number | null;
   readDisk?: () => number | null;
   /** Lists processes, or returns null where that is not possible. */
   scan?: () => ProcInfo[] | null;
@@ -92,8 +120,7 @@ export function startSampler({
   intervalMs = 2000,
   readCpu = readCpuTimes,
   readIo = readDiskBytes,
-  // Linux reports reclaimable cache as free, so this is memory programs cannot get back.
-  readMemory = () => (1 - os.freemem() / os.totalmem()) * 100,
+  readMemory = memoryPercent,
   readDisk = diskPercent,
   scan = defaultScan(),
   totalMemory = os.totalmem,
@@ -136,12 +163,11 @@ export function startSampler({
   };
 }
 
-/** Reads /proc; the environment cache lives as long as the sampler. */
+/** Reads /proc; returns null for a scan where it cannot be listed. */
 function defaultScan(): () => ProcInfo[] | null {
-  const agentIds = new Map<string, string | null>();
   return () => {
     try {
-      return readProcs(agentIds);
+      return readProcs();
     } catch {
       return null;
     }

package/shared/usage.ts

@@ -10,7 +10,7 @@ const percent = z.number().min(0).max(100);
 /** Usage of the daemon host. Percentages are 0-100; `null` means the host cannot report it yet. */
 const sample = z.object({
   cpu: percent.nullable(),
-  memory: percent,
+  memory: percent.nullable(),
   disk: percent.nullable(),
   /** Disk read plus write throughput in bytes per second. */
   io: z.number().min(0).nullable(),