paseo-plugin-machine-status 0.1.1

package/shared/explain.ts

@@ -0,0 +1,24 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const ExplanationSchema = z.object({
+  headline: z.string(),
+  kind: z.enum(["apple-system", "agent-spawned", "container", "dev-runtime", "user-app", "unknown"]),
+  state: z.enum(["just-started", "sustained-load", "memory-heavy", "steady"]),
+  concern: z.enum(["none", "watch", "act"]),
+  findings: z.array(z.string()),
+  advice: z.array(z.string()),
+});
+
+export const explainProcess = defineRpc({
+  name: "process.explain",
+  input: z.object({ pid: z.number().int().min(0) }),
+  output: z.object({
+    found: z.boolean(),
+    name: z.string(),
+    pid: z.number(),
+    explanation: ExplanationSchema,
+  }),
+});
+
+export type Explanation = z.output<typeof ExplanationSchema>;

package/shared/format.ts

@@ -0,0 +1,39 @@
+/** Presentation helpers shared by every surface. Pure functions, no runtime imports. */
+
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB", "PB"] as const;
+
+export function formatBytes(bytes: number, fractionDigits = 1): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+  const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), BYTE_UNITS.length - 1);
+  const value = bytes / 1024 ** exponent;
+  const digits = exponent === 0 ? 0 : fractionDigits;
+  return `${value.toFixed(digits)} ${BYTE_UNITS[exponent]}`;
+}
+
+export function formatPercent(value: number | null, fractionDigits = 0): string {
+  if (value === null || !Number.isFinite(value)) return "—";
+  return `${value.toFixed(fractionDigits)}%`;
+}
+
+export function formatDuration(totalSeconds: number): string {
+  if (!Number.isFinite(totalSeconds) || totalSeconds < 0) return "—";
+  const days = Math.floor(totalSeconds / 86_400);
+  const hours = Math.floor((totalSeconds % 86_400) / 3_600);
+  const minutes = Math.floor((totalSeconds % 3_600) / 60);
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  return `${minutes}m`;
+}
+
+export function formatMinutes(minutes: number | null): string {
+  if (minutes === null || !Number.isFinite(minutes) || minutes <= 0) return "—";
+  const hours = Math.floor(minutes / 60);
+  const rest = Math.round(minutes % 60);
+  return hours > 0 ? `${hours}h ${rest}m` : `${rest}m`;
+}
+
+/** Clamps a raw percentage into the 0..100 range a progress bar can render. */
+export function clampPercent(value: number | null): number {
+  if (value === null || !Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(100, value));
+}

package/shared/pill.ts

@@ -0,0 +1,63 @@
+import type { PortRow } from "./services";
+import { severityOf, type Severity } from "./viz";
+
+export interface PillReading {
+  /** What the pill shows: two percentages, nothing else fits. */
+  text: string;
+  /** The worse of the two readings, so one colour can speak for both. */
+  severity: Severity;
+  /** Spoken label, where there is room to say which number is which. */
+  label: string;
+}
+
+const RANK: Record<Severity, number> = { good: 0, warning: 1, serious: 2, critical: 3 };
+
+const show = (value: number | null): string =>
+  value === null || !Number.isFinite(value) ? "—" : `${Math.round(value)}%`;
+
+/**
+ * Reduces the machine to what fits beside a text field.
+ *
+ * CPU load and memory pressure are the two numbers that change while an agent
+ * works, and they fail in different ways: one saturates, the other swaps. Both
+ * are shown; the colour follows whichever is worse, because a pill has room for
+ * one colour and the user needs to know that something is wrong before knowing
+ * which one.
+ */
+export function pillReading(cpuLoadPercent: number, pressurePercent: number | null): PillReading {
+  const cpu = cpuSeverity(cpuLoadPercent);
+  const memory = memorySeverity(pressurePercent);
+  return {
+    text: `${show(cpuLoadPercent)} · ${show(pressurePercent)}`,
+    severity: RANK[cpu] >= RANK[memory] ? cpu : memory,
+    label: `Machine load: CPU ${show(cpuLoadPercent)}, memory ${show(pressurePercent)}`,
+  };
+}
+
+/**
+ * The thresholds the pill colours by, shared with its card so the two never
+ * disagree about the same number. CPU load reads as utilisation; memory pressure
+ * keeps the higher thresholds the pill has always used.
+ */
+export function cpuSeverity(loadPercent: number | null): Severity {
+  return severityOf(loadPercent);
+}
+
+export function memorySeverity(pressurePercent: number | null): Severity {
+  return severityOf(pressurePercent, 80, 92);
+}
+
+/**
+ * Development ports held by an agent or by a process an agent started, once per
+ * port number: the side effects of agent work that outlive the turn that made
+ * them. IPv4 and IPv6 listeners on the same port collapse into one row.
+ */
+export function agentPorts(ports: readonly PortRow[], limit = 3): PortRow[] {
+  const byPort = new Map<number, PortRow>();
+  for (const port of ports) {
+    const kind = port.attribution?.kind;
+    if (port.relevance !== "dev" || (kind !== "agent" && kind !== "agent-child")) continue;
+    if (!byPort.has(port.port)) byPort.set(port.port, port);
+  }
+  return [...byPort.values()].sort((a, b) => a.port - b.port).slice(0, limit);
+}

package/shared/services-classify.ts

@@ -0,0 +1,190 @@
+/**
+ * Runtime-neutral classification for ports and services.
+ *
+ * This module deliberately imports nothing from `@getpaseo/plugin`: the same
+ * rules are used by the Paseo plugin and by the standalone perf-agent, and the
+ * agent has no Paseo runtime to load `defineRpc` from.
+ */
+
+
+const LOOPBACK = new Set(["127.0.0.1", "::1", "localhost"]);
+const WILDCARD = new Set(["*", "0.0.0.0", "::", "[::]"]);
+
+/**
+ * A wildcard bind is reachable from the network; a loopback bind is not. The
+ * distinction is the whole point of the list, so it is computed from the address
+ * rather than guessed from the port number.
+ */
+export function scopeOf(address: string): "public" | "lan" | "local" {
+  const value = address.replace(/^\[|\]$/g, "");
+  if (WILDCARD.has(value)) return "public";
+  if (LOOPBACK.has(value)) return "local";
+  return "lan";
+}
+
+/** netstat writes `127.0.0.1.49165`, `*.3620`, `::1.15432` — the port is after the last dot. */
+export function parseNetstatAddress(field: string): { address: string; port: number } | null {
+  const index = field.lastIndexOf(".");
+  if (index <= 0) return null;
+  const port = Number(field.slice(index + 1));
+  if (!Number.isInteger(port) || port <= 0) return null;
+  return { address: field.slice(0, index), port };
+}
+
+/** lsof writes `*:49258`, `127.0.0.1:15432`, `[::1]:15432` — the port is after the last colon. */
+export function parseLsofAddress(name: string): { address: string; port: number } | null {
+  if (name.includes("->")) return null; // an established connection, not a bound socket
+  const index = name.lastIndexOf(":");
+  if (index <= 0) return null;
+  const port = Number(name.slice(index + 1));
+  if (!Number.isInteger(port) || port <= 0) return null;
+  return { address: name.slice(0, index).replace(/^\[|\]$/g, ""), port };
+}
+
+export function portKey(protocol: string, address: string, port: number): string {
+  return `${protocol}:${address.replace(/^\[|\]$/g, "")}:${port}`;
+}
+
+/**
+ * `ps` reports commands as a full path, a bare name, or a name with a version
+ * suffix (`next-server (v16.3.1)`). All three have to reduce to the same token.
+ */
+export function executableName(command: string): string {
+  const withoutVersion = command.replace(/\s*\(.*\)\s*$/, "").trim();
+  return withoutVersion.includes("/")
+    ? (withoutVersion.split("/").pop() ?? withoutVersion)
+    : withoutVersion;
+}
+
+/** Paths macOS reserves for itself. Nothing under these is development work. */
+const SYSTEM_PREFIXES = [
+  "/System/",
+  "/usr/libexec/",
+  "/usr/sbin/",
+  "/Library/Apple/",
+  "/Library/PrivilegedHelperTools/",
+];
+
+/** Runtimes and services a developer actually starts. */
+const DEV_RUNTIMES = new Set([
+  "node", "bun", "deno", "npm", "npx", "pnpm", "yarn", "tsx", "ts-node", "vite",
+  "next-server", "next", "esbuild", "webpack", "turbo", "nodemon",
+  "python", "python3", "uvicorn", "gunicorn", "flask", "django-admin",
+  "ruby", "rails", "puma", "php", "php-fpm", "java", "gradle",
+  "go", "air", "cargo", "rustc", "dotnet", "elixir", "beam.smp",
+  "postgres", "postmaster", "mysqld", "mongod", "redis-server", "valkey-server",
+  "kubectl", "minikube", "ngrok", "cloudflared", "caddy", "nginx",
+  "opencode", "claude", "codex", "kimi", "gemini", "aider", "amp", "goose",
+  "Paseo Daemon",
+]);
+
+export interface RelevanceInput {
+  kind: "agent" | "agent-child" | "docker" | "process" | null;
+  /** Full path when `ps` knows it; the bare command otherwise. */
+  command: string;
+  owner: "you" | "other";
+  home: string;
+}
+
+/**
+ * Development ports are identified by evidence, never by port number. Ranges do
+ * not separate them: 5000 and 7000 here are AirPlay, while 49165 is a coding
+ * agent.
+ */
+export function classifyRelevance({ kind, command, owner, home }: RelevanceInput): "dev" | "system" {
+  if (kind === "agent" || kind === "agent-child" || kind === "docker") return "dev";
+  if (owner === "other") return "system";
+  if (SYSTEM_PREFIXES.some((prefix) => command.startsWith(prefix))) return "system";
+
+  const name = executableName(command);
+  if (DEV_RUNTIMES.has(name)) return "dev";
+  if (/^com\.docker/.test(name)) return "dev";
+
+  // Anything the user installed or built under their own home, except the
+  // Library tree, which is where macOS keeps per-user daemons.
+  if (home.length > 0 && command.startsWith(`${home}/`) && !command.startsWith(`${home}/Library/`)) {
+    return "dev";
+  }
+  return "system";
+}
+
+/**
+ * Known binaries get a readable name. Everything else keeps the command it
+ * actually runs — inventing a plausible service name would make the list read as
+ * knowledge it does not have.
+ */
+const NAMES: readonly (readonly [RegExp, string])[] = [
+  [/^vite$|[/\s]vite$/i, "Vite dev server"],
+  [/next-server|^next$/i, "Next.js"],
+  [/^postgres$|^postmaster$/i, "PostgreSQL"],
+  [/^redis-server$/i, "Redis"],
+  [/^valkey/i, "Valkey"],
+  [/^mysqld$/i, "MySQL"],
+  [/^mongod$/i, "MongoDB"],
+  [/^sshd$/i, "OpenSSH"],
+  [/^tailscaled?$/i, "Tailscale"],
+  [/^com\.docke|^docker/i, "Docker"],
+  [/^esbuild$/i, "esbuild"],
+  [/^ControlCenter$/i, "Control Center"],
+  [/^rapportd$/i, "Handoff (rapportd)"],
+  [/^kubectl/i, "kubectl port-forward"],
+];
+
+export function friendlyName(command: string): string {
+  const base = command.split("/").pop() ?? command;
+  for (const [pattern, name] of NAMES) {
+    if (pattern.test(base)) return name;
+  }
+  return base;
+}
+
+/** Only a locally reachable TCP port can be opened in a browser. */
+export function httpUrlFor(row: {
+  protocol: string;
+  scope: string;
+  port: number;
+}): string | null {
+  if (row.protocol !== "tcp") return null;
+  if (row.scope === "lan") return null;
+  return `http://127.0.0.1:${row.port}`;
+}
+
+/**
+ * The SDK's list shape is not pinned down by the docs, so the result is read
+ * defensively: an array, or the first array-valued key of an object. A shape
+ * change degrades this panel instead of breaking the whole RPC.
+ */
+export function normalizeAgents(
+  raw: unknown,
+  /** Expands the `~/…` form the Paseo CLI prints; the SDK returns absolute paths. */
+  home = "",
+): {
+  id: string;
+  provider: string;
+  cwd: string;
+  title: string;
+  status: string;
+}[] {
+  const list = Array.isArray(raw)
+    ? raw
+    : raw && typeof raw === "object"
+      ? (Object.values(raw as Record<string, unknown>).find(Array.isArray) as unknown[] | undefined) ?? []
+      : [];
+
+  return list
+    .filter((entry): entry is Record<string, unknown> => !!entry && typeof entry === "object")
+    .map((entry) => {
+      const config = (entry.config ?? {}) as Record<string, unknown>;
+      const provider = String(entry.provider ?? config.provider ?? "");
+      const cwd = String(entry.cwd ?? "");
+      return {
+        id: String(entry.id ?? ""),
+        // "codex/gpt-5.5" identifies the binary by its first segment.
+        provider: provider.split("/")[0]?.toLowerCase() ?? "",
+        cwd: home && cwd.startsWith("~/") ? `${home}/${cwd.slice(2)}` : cwd,
+        title: String(entry.title ?? entry.name ?? ""),
+        status: String(entry.status ?? ""),
+      };
+    })
+    .filter((agent) => agent.provider.length > 0);
+}

package/shared/services.ts

@@ -0,0 +1,52 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const PortSchema = z.object({
+  id: z.string(),
+  port: z.number(),
+  protocol: z.enum(["tcp", "udp"]),
+  address: z.string(),
+  scope: z.enum(["public", "lan", "local"]),
+  pid: z.number().nullable(),
+  command: z.string().nullable(),
+  /** "other" means the socket exists but belongs to a user we cannot inspect. */
+  owner: z.enum(["you", "other"]),
+  /** Whether this port belongs to development work or to the OS. */
+  relevance: z.enum(["dev", "system"]),
+  attribution: z
+    .object({
+      kind: z.enum(["agent", "agent-child", "docker", "process"]),
+      label: z.string(),
+      detail: z.string(),
+    })
+    .nullable(),
+  url: z.string().nullable(),
+});
+
+export const ServiceSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  subtitle: z.string(),
+  ports: z.array(z.number()),
+  status: z.enum(["running", "stopped"]),
+  source: z.enum(["agent", "agent-child", "docker", "listener"]),
+  relevance: z.enum(["dev", "system"]),
+  pid: z.number().nullable(),
+});
+
+export const readServices = defineRpc({
+  name: "services.read",
+  input: z.object({}),
+  output: z.object({
+    collectedAt: z.string(),
+    ports: z.array(PortSchema),
+    services: z.array(ServiceSchema),
+    /** Anything the collection could not see, stated rather than silently dropped. */
+    notes: z.array(z.string()),
+  }),
+});
+
+export type PortRow = z.output<typeof PortSchema>;
+export type ServiceRow = z.output<typeof ServiceSchema>;
+
+export * from "./services-classify";

package/shared/viz.ts

@@ -0,0 +1,159 @@
+/**
+ * Chart palette and geometry. Pure values and pure functions only, so the colour
+ * decisions and the bar maths are both testable without a renderer.
+ *
+ * Paseo exposes six theme tokens and never says which theme is active, so the
+ * data palette is chosen by measuring the luminance of `surface0`. Chrome comes
+ * from the theme; series colour does not — a categorical hue has to stay the
+ * same hue across themes or it stops identifying anything.
+ *
+ * Both columns below are the reference categorical order and were validated with
+ * scripts/validate_palette.js against their own surface: every hard gate passes
+ * in both modes (worst adjacent CVD ΔE 8.4 dark / 9.1 light, normal-vision 19.8
+ * dark / 22.9 light). The light column's aqua and yellow sit under 3:1, which the
+ * relief rule permits because every series is directly labelled with its value.
+ */
+
+export interface VizPalette {
+  /** Categorical slots in fixed order. Assigned by slot, never cycled. */
+  series: readonly [string, string, string, string];
+  /** For "free"/"unused" remainders, which are an absence rather than a category. */
+  neutral: string;
+  grid: string;
+  /**
+   * Hairline ring. Deliberately NOT a text token: `foregroundMuted` is tuned to be
+   * legible as type, which makes it far too loud for a 1px edge.
+   */
+  border: string;
+  borderStrong: string;
+}
+
+export const DARK_PALETTE: VizPalette = {
+  series: ["#3987e5", "#d95926", "#199e70", "#c98500"],
+  neutral: "#383835",
+  grid: "#2c2c2a",
+  border: "rgba(255,255,255,0.10)",
+  borderStrong: "rgba(255,255,255,0.18)",
+};
+
+export const LIGHT_PALETTE: VizPalette = {
+  series: ["#2a78d6", "#eb6834", "#1baf7a", "#eda100"],
+  neutral: "#c3c2b7",
+  grid: "#e1e0d9",
+  border: "rgba(11,11,11,0.10)",
+  borderStrong: "rgba(11,11,11,0.18)",
+};
+
+/** Fixed across themes: a status colour must never impersonate a series. */
+export const STATUS = {
+  good: "#0ca30c",
+  warning: "#fab219",
+  serious: "#ec835a",
+  critical: "#d03b3b",
+} as const;
+
+export type Severity = keyof typeof STATUS;
+
+const HEX = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
+const RGB = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i;
+
+function channel(value: number): number {
+  const c = value / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** WCAG relative luminance, or null when the colour is in a format we cannot read. */
+export function relativeLuminance(color: string): number | null {
+  const trimmed = color.trim();
+
+  const hex = HEX.exec(trimmed);
+  if (hex) {
+    const digits = hex[1].length === 3 ? hex[1].replace(/./g, (d) => d + d) : hex[1];
+    const [r, g, b] = [0, 2, 4].map((offset) => parseInt(digits.slice(offset, offset + 2), 16));
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+  }
+
+  const rgb = RGB.exec(trimmed);
+  if (rgb) {
+    const [r, g, b] = [1, 2, 3].map((index) => Number(rgb[index]));
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+  }
+
+  return null;
+}
+
+/** Unreadable colour formats fall back to dark, which is Paseo's default. */
+export function isDarkSurface(color: string): boolean {
+  const luminance = relativeLuminance(color);
+  return luminance === null ? true : luminance < 0.4;
+}
+
+export function paletteFor(surface: string): VizPalette {
+  return isDarkSurface(surface) ? DARK_PALETTE : LIGHT_PALETTE;
+}
+
+/**
+ * Severity for a utilisation percentage. Always paired with a text label in the
+ * UI: a status colour never carries the meaning on its own.
+ */
+export function severityOf(percent: number | null, warnAt = 75, criticalAt = 90): Severity {
+  if (percent === null || !Number.isFinite(percent)) return "good";
+  if (percent >= criticalAt) return "critical";
+  if (percent >= warnAt) return "warning";
+  return "good";
+}
+
+export const SEVERITY_LABEL: Record<Severity, string> = {
+  good: "OK",
+  warning: "High",
+  serious: "Serious",
+  critical: "Critical",
+};
+
+/** Column heights as percentages, for a bar-per-sample chart. */
+export function columnHeights(values: readonly number[], min: number, max: number): number[] {
+  const span = max - min;
+  if (span <= 0) return values.map(() => 0);
+  return values.map((value) => {
+    const clamped = Math.max(min, Math.min(max, value));
+    return ((clamped - min) / span) * 100;
+  });
+}
+
+/**
+ * Splits one stacked column into segment percentages of `total`. The remainder is
+ * returned as the last entry so the column always sums to 100.
+ */
+export function stackedColumn(parts: readonly number[], total: number): number[] {
+  if (total <= 0) return parts.map(() => 0).concat(100);
+  const segments = parts.map((part) => Math.max(0, (part / total) * 100));
+  const used = segments.reduce((sum, segment) => sum + segment, 0);
+  return segments.concat(Math.max(0, 100 - used));
+}
+
+/**
+ * Right-aligns a series into a fixed number of slots, padding the left with nulls.
+ *
+ * A live monitor's plot has a constant width whether or not history has filled it:
+ * the newest sample belongs at the right edge next to "now", and the empty left is
+ * the honest picture of how much history exists. Stretching a handful of samples
+ * across the full width would instead imply they span the whole window.
+ */
+export function padSlots<T>(values: readonly T[], slots: number): (T | null)[] {
+  if (slots <= 0) return [];
+  if (values.length >= slots) return values.slice(values.length - slots) as T[];
+  return [...new Array<null>(slots - values.length).fill(null), ...values];
+}
+
+export function takeLast<T>(items: readonly T[], count: number): T[] {
+  return count >= items.length ? [...items] : items.slice(items.length - count);
+}
+
+/** Human span between the first and last sample, for an honest axis caption. */
+export function spanLabel(first: string | undefined, last: string | undefined): string {
+  if (!first || !last) return "no history yet";
+  const seconds = Math.round((Date.parse(last) - Date.parse(first)) / 1000);
+  if (!Number.isFinite(seconds) || seconds <= 0) return "just started";
+  if (seconds < 90) return `last ${seconds}s`;
+  return `last ${Math.round(seconds / 60)} min`;
+}