@omercnet/paseo-top 0.0.0-stage → 0.0.1-next.250.1

package/client/usage.ts

@@ -0,0 +1,16 @@
+import { useRpc } from "@getpaseo/plugin/client";
+import { useQuery } from "@tanstack/react-query";
+import { getUsage } from "../shared/usage";
+
+export const SCREEN_ID = "usage";
+export const POLL_MS = 5000;
+
+export function useUsage(hostId: string) {
+  const loadUsage = useRpc(getUsage);
+  // The host id keys the cache so a host switch never shows another host's numbers.
+  return useQuery({
+    queryKey: ["top", hostId, "usage"],
+    queryFn: () => loadUsage({}),
+    refetchInterval: POLL_MS,
+  });
+}

package/index.client.tsx

@@ -0,0 +1,17 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { TopFooter } from "./client/footer";
+import { TopScreen } from "./client/screen";
+import { SCREEN_ID } from "./client/usage";
+
+export default function contribute(client: PluginClientContext) {
+  const removeScreen = client.addScreen({ id: SCREEN_ID, title: "Top", Component: TopScreen });
+  const removeFooter = client.addSidebarFooterItem({
+    id: SCREEN_ID,
+    title: "Top",
+    Component: TopFooter,
+  });
+  return () => {
+    removeFooter();
+    removeScreen();
+  };
+}

package/index.server.ts

@@ -0,0 +1,18 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { createOwnership } from "./server/names";
+import { startSampler } from "./server/usage";
+import { getUsage } from "./shared/usage";
+
+export default function contribute(server: PluginServerContext) {
+  const sampler = startSampler();
+  const ownSessions = createOwnership();
+  server.handle(getUsage, async (_input, { paseo }) => {
+    const usage = sampler.usage();
+    if (!usage.sessions) return usage;
+    return { ...usage, ...(await ownSessions(paseo, usage.sessions, usage.other)) };
+  });
+  return () => {
+    sampler.stop();
+    ownSessions.stop();
+  };
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@omercnet/paseo-top",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omercnet/paseo-plugins.git",
+    "directory": "top"
+  },
+  "homepage": "https://github.com/omercnet/paseo-plugins/tree/main/top#readme",
+  "bugs": {
+    "url": "https://github.com/omercnet/paseo-plugins/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.4.2",
+  "engines": {
+    "node": ">=24"
+  },
+  "author": "Omer Cohen",
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "top",
+    "host-monitor"
+  ],
+  "files": [
+    "index.client.tsx",
+    "index.server.ts",
+    "client",
+    "server",
+    "shared",
+    "paseo-plugin.json",
+    "README.md",
+    "LICENSE",
+    "OVERVIEW.md"
+  ],
+  "scripts": {
+    "check": "biome check .",
+    "check:write": "biome check --write .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.10",
+    "@getpaseo/cli": "0.11.1",
+    "@getpaseo/client": "0.11.1",
+    "@getpaseo/plugin": "0.11.1",
+    "@getpaseo/protocol": "0.11.1",
+    "@tanstack/react-query": "^5.102.3",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.18",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0",
+    "zod": "4.4.3"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +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

@@ -0,0 +1,177 @@
+import type { PaseoApi } from "@getpaseo/client";
+import type { Session } from "../shared/usage";
+
+/** Re-reading every agent, archived ones included, is not free, so it is done sparingly. */
+const FULL_REFRESH_MS = 30_000;
+/** A session whose agent is not yet known may be a brand new agent; look again, but not constantly. */
+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;
+
+interface Load {
+  cores: number;
+  rss: number;
+}
+
+interface Known {
+  agents: Map<string, { title: string | null; workspaceId: string | null }>;
+  workspaces: Map<string, string>;
+}
+
+interface Page<T> {
+  entries: T[];
+  pageInfo: { hasMore: boolean; nextCursor: string | null };
+}
+
+/**
+ * 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 Promise.race([fetchPage(cursor), aborted]);
+    entries.push(...result.entries);
+    if (!result.pageInfo.hasMore || !result.pageInfo.nextCursor) break;
+    cursor = result.pageInfo.nextCursor;
+  }
+  return entries;
+}
+
+/**
+ * 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.
+ *
+ * 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. 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: { done: Promise<void>; startedAt: number; abort: AbortController } | null = null;
+
+  const refresh = (paseo: PaseoApi, candidates: string[]) => {
+    if (inflight && now() - inflight.startedAt >= REFRESH_LIFETIME_MS) {
+      inflight.abort.abort();
+      inflight = null;
+    }
+    if (inflight) return inflight.done;
+    fetchedAt = now();
+    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(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,
+            }),
+          ),
+          // 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 }) => [
+              agent.id,
+              { title: agent.title ?? null, workspaceId: agent.workspaceId ?? null },
+            ]),
+          ),
+          workspaces: new Map(
+            workspaces.map((workspace) => [workspace.id, workspace.title ?? workspace.name]),
+          ),
+        };
+        known = next;
+        foreign = new Set(candidates.filter((id) => !next.agents.has(id)));
+      } catch {
+        // Keep the previous lists.
+      } finally {
+        if (inflight === run) inflight = null;
+      }
+    })();
+    return run.done;
+  };
+
+  const ownership = async (paseo: PaseoApi, sessions: Session[], other: Load) => {
+    if (sessions.length === 0) return { sessions, other };
+
+    const ids = sessions.map((session) => session.agentId);
+    const age = now() - fetchedAt;
+    const unseen = ids.some((id) => !known?.agents.has(id) && !foreign.has(id));
+    const pending =
+      age >= FULL_REFRESH_MS || (unseen && age >= EARLY_REFRESH_MS)
+        ? refresh(paseo, ids)
+        : inflight?.done;
+    if (known === null && pending) {
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, firstFetchTimeoutMs);
+        pending.then(() => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+    }
+
+    const rest = { ...other };
+    const own: Session[] = [];
+    for (const session of sessions) {
+      const agent = known?.agents.get(session.agentId);
+      if (!agent) {
+        rest.cores += session.cores;
+        rest.rss += session.rss;
+        continue;
+      }
+      own.push({
+        ...session,
+        title: agent.title,
+        workspace: (agent.workspaceId && known?.workspaces.get(agent.workspaceId)) || null,
+      });
+    }
+    // Callers hand sessions over flagged first, then busiest, so the cap drops the least important.
+    for (const session of own.slice(MAX_SESSIONS)) {
+      rest.cores += session.cores;
+      rest.rss += session.rss;
+    }
+    return { sessions: own.slice(0, MAX_SESSIONS), other: rest };
+  };
+
+  return Object.assign(ownership, {
+    stop: () => {
+      inflight?.abort.abort();
+      inflight = null;
+    },
+  });
+}

package/server/processes.ts

@@ -0,0 +1,260 @@
+import { readdirSync, readFileSync } from "node:fs";
+import os from "node:os";
+import type { Session } from "../shared/usage";
+
+const CLOCK_TICKS = 100;
+const CPUS = Math.max(1, os.availableParallelism());
+const MAX_DEPTH = 64;
+const DEFAULT_PAGE_BYTES = 4096;
+const AT_PAGESZ = 6;
+
+/** The kernel's page size from the auxiliary vector; arm64 and ppc64 kernels often use 16K or 64K. */
+export function readPageSize(auxvPath = "/proc/self/auxv"): number {
+  try {
+    const auxv = readFileSync(auxvPath);
+    const little = os.endianness() === "LE";
+    // Entries are (type, value) pairs of machine words; 64-bit hosts are the only ones in practice.
+    for (let at = 0; at + 16 <= auxv.length; at += 16) {
+      const type = Number(little ? auxv.readBigUInt64LE(at) : auxv.readBigUInt64BE(at));
+      if (type !== AT_PAGESZ) continue;
+      const value = Number(little ? auxv.readBigUInt64LE(at + 8) : auxv.readBigUInt64BE(at + 8));
+      const power = value > 0 && (value & (value - 1)) === 0;
+      return power && value >= DEFAULT_PAGE_BYTES && value <= 2 ** 20 ? value : DEFAULT_PAGE_BYTES;
+    }
+  } catch {
+    // Not Linux, or not readable.
+  }
+  return DEFAULT_PAGE_BYTES;
+}
+
+export const PAGE_BYTES = readPageSize();
+
+export interface ProcInfo {
+  /** `pid:starttime`, unique even after the kernel reuses a pid. */
+  key: string;
+  pid: number;
+  ppid: number;
+  /** User plus system CPU time so far, in ticks. */
+  ticks: number;
+  rss: number;
+  comm: string;
+  /** Agent that launched this process, from the environment Paseo gave it, if any. */
+  agentId: string | null;
+}
+
+export interface Stat {
+  ppid: number;
+  ticks: number;
+  start: number;
+  rss: number;
+  comm: string;
+}
+
+/** Parses /proc/<pid>/stat. The command may contain spaces and parentheses, so split at the last `)`. */
+export function parseStat(text: string): Stat | null {
+  const open = text.indexOf("(");
+  const close = text.lastIndexOf(")");
+  if (open < 0 || close < open) return null;
+  // Fields after the command start at number 3, so field n is at index n - 3.
+  const fields = text.slice(close + 2).split(" ");
+  const numbers = {
+    ppid: Number(fields[1]),
+    ticks: Number(fields[11]) + Number(fields[12]),
+    start: Number(fields[19]),
+    rss: Number(fields[21]) * PAGE_BYTES,
+  };
+  if (!Object.values(numbers).every(Number.isFinite)) return null;
+  // The kernel reports rss as a signed number; a negative one must not poison the whole reading.
+  return { comm: text.slice(open + 1, close), ...numbers, rss: Math.max(0, numbers.rss) };
+}
+
+/** 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;
+  }
+  return null;
+}
+
+/**
+ * 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(root = "/proc"): ProcInfo[] {
+  const procs: ProcInfo[] = [];
+  for (const name of readdirSync(root)) {
+    if (!/^\d+$/.test(name)) continue;
+    try {
+      const stat = parseStat(readFileSync(`${root}/${name}/stat`, "utf8"));
+      if (!stat) continue;
+      let agentId: string | null;
+      try {
+        agentId = parseAgentId(readFileSync(`${root}/${name}/environ`, "utf8"));
+      } catch {
+        agentId = null;
+      }
+      procs.push({ key: `${name}:${stat.start}`, pid: Number(name), agentId, ...stat });
+    } catch {
+      // The process exited while it was being read.
+    }
+  }
+  return procs;
+}
+
+export interface SessionLoad {
+  agentId: string;
+  cores: number;
+  rss: number;
+  command: string;
+  processes: number;
+}
+
+export interface Attribution {
+  sessions: SessionLoad[];
+  other: { cores: number; rss: number };
+  /** CPU ticks per process, to diff against on the next scan. */
+  ticks: Map<string, number>;
+}
+
+/**
+ * Charges each process to the agent that launched it. Tools often scrub or reset their
+ * environment, so an untagged process inherits from its nearest tagged ancestor.
+ *
+ * `previous` is the last scan's ticks, or null for the very first scan, which has nothing to diff
+ * against and so charges no CPU. After that, a process that is new since the last scan is charged
+ * all the CPU it has used, bounded by what every CPU could have given in the interval.
+ */
+export function attribute(
+  procs: readonly ProcInfo[],
+  previous: ReadonlyMap<string, number> | null,
+  elapsedSeconds: number,
+): Attribution {
+  const byPid = new Map(procs.map((proc) => [proc.pid, proc]));
+  const ticks = new Map<string, number>();
+  const sessions = new Map<string, SessionLoad & { topCores: number; topRss: number }>();
+  const other = { cores: 0, rss: 0 };
+  const budget = elapsedSeconds * CLOCK_TICKS * CPUS;
+
+  for (const proc of procs) {
+    ticks.set(proc.key, proc.ticks);
+    let owner = proc;
+    for (let depth = 0; !owner.agentId && depth < MAX_DEPTH; depth++) {
+      const parent = byPid.get(owner.ppid);
+      if (!parent || parent === owner) break;
+      owner = parent;
+    }
+    let cores = 0;
+    if (previous && elapsedSeconds > 0) {
+      const earlier = previous.get(proc.key);
+      // A process seen before has a monotonic counter. One that is new since the last scan has used
+      // all its ticks within the interval; the bound only guards against a process missed earlier.
+      const used = earlier === undefined ? Math.min(proc.ticks, budget) : proc.ticks - earlier;
+      cores = Math.max(0, used) / CLOCK_TICKS / elapsedSeconds;
+    }
+
+    if (!owner.agentId) {
+      other.cores += cores;
+      other.rss += proc.rss;
+      continue;
+    }
+    let session = sessions.get(owner.agentId);
+    if (!session) {
+      session = {
+        agentId: owner.agentId,
+        cores: 0,
+        rss: 0,
+        command: proc.comm,
+        processes: 0,
+        topCores: -1,
+        topRss: -1,
+      };
+      sessions.set(owner.agentId, session);
+    }
+    session.cores += cores;
+    session.rss += proc.rss;
+    session.processes++;
+    // The busiest process names the load; memory breaks ties between equally busy ones.
+    if (cores > session.topCores || (cores === session.topCores && proc.rss > session.topRss)) {
+      session.topCores = cores;
+      session.topRss = proc.rss;
+      session.command = proc.comm;
+    }
+  }
+
+  return {
+    sessions: [...sessions.values()].map(
+      ({ topCores: _cores, topRss: _rss, ...session }) => session,
+    ),
+    other,
+    ticks,
+  };
+}
+
+export const SCAN_EVERY_MS = 10_000;
+/** A session is heavy at one busy core held for three scans (30 seconds), or a quarter of memory. */
+export const HEAVY_CORES = 1;
+export const HEAVY_SCANS = 3;
+export const HEAVY_MEMORY_SHARE = 0.25;
+
+/**
+ * Rescans every `SCAN_EVERY_MS` and remembers a short window of each session's CPU, so a one-scan
+ * spike does not flag it. `scan` returns null where processes cannot be listed: for good on a host
+ * that cannot do it at all (not Linux), and for one scan on a host that failed once.
+ */
+export function trackSessions(scan: () => ProcInfo[] | null, startedAt: number) {
+  const first = scan();
+  const supported = first !== null;
+  let previous = first ? attribute(first, null, 0).ticks : new Map<string, number>();
+  let latest: Pick<Attribution, "sessions" | "other"> = {
+    sessions: [],
+    other: { cores: 0, rss: 0 },
+  };
+  let scannedAt = startedAt;
+  let failures = 0;
+  let recent = new Map<string, number[]>();
+
+  return {
+    update(at: number) {
+      if (!supported || at - scannedAt < SCAN_EVERY_MS) return;
+      const procs = scan();
+      if (!procs) {
+        // Keep the last readings through a hiccup, but not through a lasting failure. The next
+        // good scan diffs against the last good one, over the longer interval.
+        if (++failures >= HEAVY_SCANS) {
+          latest = { sessions: [], other: { cores: 0, rss: 0 } };
+          recent = new Map();
+        }
+        return;
+      }
+      failures = 0;
+      const next = attribute(procs, previous, (at - scannedAt) / 1000);
+      previous = next.ticks;
+      scannedAt = at;
+      latest = { sessions: next.sessions, other: next.other };
+      recent = new Map(
+        next.sessions.map(({ agentId, cores }) => [
+          agentId,
+          [...(recent.get(agentId) ?? []), cores].slice(-HEAVY_SCANS),
+        ]),
+      );
+    },
+    read(totalMemory: number): {
+      sessions: Session[] | null;
+      other: { cores: number; rss: number };
+    } {
+      if (!supported) return { sessions: null, other: { cores: 0, rss: 0 } };
+      const sessions = latest.sessions
+        .map((session): Session => {
+          const window = recent.get(session.agentId) ?? [];
+          // Held for the whole window, not averaged, so one burst does not flag a session.
+          const sustained = window.length === HEAVY_SCANS && window.every((c) => c >= HEAVY_CORES);
+          const heavy = sustained || session.rss >= HEAVY_MEMORY_SHARE * totalMemory;
+          return { ...session, title: null, workspace: null, heavy };
+        })
+        .sort((a, b) => Number(b.heavy) - Number(a.heavy) || b.cores - a.cores || b.rss - a.rss);
+      return { sessions, other: latest.other };
+    },
+  };
+}