paseo-plugin-machine-status 0.1.1 → 0.2.0

package/OVERVIEW.md

@@ -0,0 +1,26 @@
+Machine Status shows what the daemon's Mac is doing while your agents work: CPU load, memory pressure, swap, disk, battery and thermal state, the ports and background processes your agents started, and the Docker engine. It also clears developer caches and stops runaway processes, with a confirmation step for each.
+
+## What you get
+
+- **Machine screen**, opened from the sidebar or ⌘K. Overview has stat tiles that expand into detail, CPU and memory charts, a dev-cache scanner, and a process table. Ports & services lists listening ports and what runs behind them. Docker shows the engine, containers and disk usage.
+- **Load pill** beside every agent's composer with CPU load and memory pressure. Pressing it opens a compact card with the trend, the top CPU processes, and the development ports held by agents, so you can tell whether the machine is the problem without leaving the chat.
+- On Paseo 0.11 and newer, ⌘K can open the screen straight on Ports & services or Docker.
+
+## How it decides
+
+- Memory follows Activity Monitor's split, and the pressure figure is macOS's own. Cached files are not counted as used.
+- A background process belongs to an agent when it descends from the Paseo daemon in the process tree, not when its name looks like a provider. A port counts as a development port by its executable's path, not by its number. System ports are hidden until you choose **Show system**.
+- Values the plugin cannot read are shown as missing rather than estimated. Per-core utilisation is not shown at all.
+
+## Setup
+
+- A macOS daemon on Paseo 0.8 to 0.11. On other platforms the screen says it cannot collect metrics.
+- Docker Desktop, OrbStack or Rancher Desktop for the Docker tab. Without one, the tab says which is missing.
+
+## What it can change
+
+- **Dev caches**: only a fixed list of caches that their tools recreate (npm, pnpm, Yarn, Bun, Turbo, Xcode DerivedData, Cargo, Go, pip, uv). The client sends a cache id, never a path; each path must resolve below your home directory, and only its contents are removed.
+- **Processes**: SIGTERM first, and force kill only as a separate confirmed step. Paseo and its parent processes are protected and checked again on every kill.
+- **Docker**: start, stop, restart and remove containers, quit or start the engine, and prune stopped containers and dangling images. Volumes are never pruned.
+
+Everything runs on the daemon through local commands such as `vm_stat`, `ps`, `lsof`, `netstat` and `docker`. Nothing is sent off the machine.

package/README.md

@@ -56,7 +56,10 @@ paseo plugin ls          # expect: running
 Plugins must be enabled daemon-wide first, under **Settings → Plugins → Enable
 plugins** (the root `pluginsEnabled` field in `~/.paseo/config.json`).
 
-Open it from the **Machine** sidebar item, or ⌘K → "Machine status".
+Open it from the **Machine** sidebar item, or ⌘K → "Machine status". On Paseo 0.11
+and newer, ⌘K also offers "Machine: ports & services" and "Machine: Docker", which
+open straight on that tab, and the tab travels in the screen's link (`?tab=services`,
+`?tab=docker`), so reload and back keep it.
 
 ## The screen
 
@@ -328,8 +331,7 @@ confirmed step.
 ## Development
 
 ```bash
-npm run typecheck
-npm test                              # 237 tests
+npm run check                         # typecheck, then the tests
 paseo plugin reload machine-status    # source edits need an explicit reload
 paseo plugin logs machine-status
 npm run preview                       # regenerates docs/preview.svg from the real palette
@@ -344,15 +346,35 @@ would otherwise surface as an RPC rejection at runtime. The live tests never
 mutate anything: cleanup is only planned, and the kill tests assert refusals,
 including a refusal to terminate the test runner itself.
 
-The SDK remains pinned to 0.8.0 as the development baseline for typechecking and
-tests. Paseo supplies the runtime instances on every supported release line, so
-none of it ships with the plugin.
+### Paseo versions
+
+The SDK stays pinned to 0.8.0 for typechecking and tests, so the compiler proves
+the plugin uses only the oldest supported API. Paseo supplies the runtime instances
+on every supported release line, so none of it ships with the plugin.
+
+Paseo 0.11 replaced surfaces with screens and kept the old calls as deprecated
+aliases. The manifest still admits 0.8, and each connected app evaluates the client
+entry against its own version, so `client/compat.tsx` describes the 0.11 additions
+locally and calls them only after checking that the app has them:
+
+| App version | Screen | Sidebar | Opens with | Tab shortcuts in ⌘K |
+| ----------- | ------ | ------- | ---------- | ------------------- |
+| 0.11 and newer | `addScreen` | `addSidebarHeaderItem` + `SidebarRow` | `openScreen`, with `?tab=` | yes |
+| 0.8 to 0.10 | `addSurface` | `addSidebarItem` | `openSurface`, overview tab | not offered |
+
+Both paths register under the id `main`, so saved `/plugin/machine-status/main`
+links open the same screen after an upgrade. `tests/compat.test.ts` pins both
+paths, including a half-present API, which falls back rather than mixing the two.
+The daemon half uses only `server.handle`, which has not changed since 0.8.
+
+Releases are cut from tags by GitHub Actions; see [CONTRIBUTING.md](CONTRIBUTING.md)
+for the flow and [CHANGELOG.md](CHANGELOG.md) for what changed.
 
 ## Troubleshooting
 
 | Symptom | Check |
 | ------- | ----- |
-| Sidebar item missing | `paseo plugin ls` reports `running`, and the client is on this host |
+| Sidebar item missing | `paseo plugin ls` reports `running`, the client is on this host, and on 0.11+ the item is not hidden in **Settings → Sidebar** |
 | "Metrics unavailable" | The daemon is not on macOS, or a `/usr/bin` tool is missing |
 | Charts look empty | History starts empty; it fills as the tab stays open |
 | A port shows "another user" | It belongs to root or another account; `lsof` cannot inspect it unprivileged |

package/client/compat.tsx

@@ -0,0 +1,123 @@
+import type {
+  PluginClientContext,
+  PluginCommandCapabilities,
+  PluginHostProps,
+  PluginSurfaceProps,
+} from "@getpaseo/plugin/client";
+import * as ui from "@getpaseo/plugin/client/ui";
+import type { ComponentType, FunctionComponent } from "react";
+
+/**
+ * Paseo 0.11 replaced surfaces with screens: `addScreen`, `addSidebarHeaderItem`
+ * and `openScreen`. The manifest still admits 0.8, and every connected app runs
+ * this entry against its own version, so each call checks for the new method and
+ * falls back to the old one.
+ *
+ * The SDK stays pinned to 0.8.0 so typechecking proves the rest of the plugin
+ * uses only the oldest supported API. The 0.11 additions are described here,
+ * from the 0.11 SDK declarations, and are reachable only behind a runtime check.
+ */
+
+const SCREEN_ID = "main";
+const TITLE = "Machine";
+const ICON = "Activity";
+
+/** String keys and values: 0.11 carries them in the screen's URL. */
+export type ScreenParams = Record<string, string>;
+
+interface OpenScreenInput {
+  screenId: string;
+  params?: ScreenParams;
+}
+
+interface SidebarItemProps extends PluginHostProps {
+  currentScreen: { screenId: string; params: ScreenParams } | null;
+  openScreen(input: OpenScreenInput): void;
+}
+
+/** What 0.11 adds to the client context. */
+interface ScreenApi {
+  addScreen(contribution: {
+    id: string;
+    title: string;
+    Component: ComponentType<MachineScreenProps>;
+  }): () => void;
+  addSidebarHeaderItem(contribution: {
+    id: string;
+    title: string;
+    Component: ComponentType<SidebarItemProps>;
+  }): () => void;
+}
+
+/** What 0.11 adds to command and slash-command callbacks. */
+interface OpenScreenApi {
+  openScreen(input: OpenScreenInput): void;
+}
+
+/** `@getpaseo/plugin/client/ui` gained this in 0.11; the older app runtime has no such export. */
+type SidebarRowComponent = ComponentType<{ icon?: string; active?: boolean; onPress(): void }>;
+
+/** What the screen receives on either API: 0.11 adds `params`, older hosts do not. */
+export type MachineScreenProps = PluginSurfaceProps & { params?: ScreenParams };
+
+function screenApi(client: PluginClientContext): ScreenApi | null {
+  const candidate = client as PluginClientContext & Partial<ScreenApi>;
+  return typeof candidate.addScreen === "function" && typeof candidate.addSidebarHeaderItem === "function"
+    ? (candidate as PluginClientContext & ScreenApi)
+    : null;
+}
+
+function openScreenApi(capabilities: object): OpenScreenApi | null {
+  const candidate = capabilities as Partial<OpenScreenApi>;
+  return typeof candidate.openScreen === "function" ? (candidate as OpenScreenApi) : null;
+}
+
+export function registerMachineScreen(
+  client: PluginClientContext,
+  Component: FunctionComponent<MachineScreenProps>,
+): void {
+  const screens = screenApi(client);
+  if (screens) {
+    screens.addScreen({ id: SCREEN_ID, title: TITLE, Component });
+    // Same id as the old sidebar item, so saved `/plugin/machine-status/main` links keep working.
+    screens.addSidebarHeaderItem({ id: SCREEN_ID, title: TITLE, Component: MachineSidebarItem });
+    return;
+  }
+  client.addSurface(SCREEN_ID, Component);
+  client.addSidebarItem({ id: SCREEN_ID, title: TITLE, icon: ICON, surface: SCREEN_ID });
+}
+
+function MachineSidebarItem({ currentScreen, openScreen }: SidebarItemProps) {
+  // Read off the namespace: the 0.8–0.10 ui runtime has no SidebarRow, and the
+  // item renders nothing rather than crash.
+  const SidebarRow = (ui as { SidebarRow?: SidebarRowComponent }).SidebarRow;
+  if (!SidebarRow) return null;
+  return (
+    <SidebarRow
+      icon={ICON}
+      active={currentScreen?.screenId === SCREEN_ID}
+      onPress={() => openScreen({ screenId: SCREEN_ID })}
+    />
+  );
+}
+
+/**
+ * Opens the Machine screen, on a tab when the host can carry params. Pre-0.11
+ * hosts open the surface on its default tab.
+ */
+export function openMachineScreen(
+  capabilities: Pick<PluginCommandCapabilities, "openSurface">,
+  params?: ScreenParams,
+): void {
+  const screens = openScreenApi(capabilities);
+  if (screens) {
+    screens.openScreen(params ? { screenId: SCREEN_ID, params } : { screenId: SCREEN_ID });
+    return;
+  }
+  capabilities.openSurface(SCREEN_ID);
+}
+
+/** True on 0.11+ apps, where a command can land on a specific tab. */
+export function supportsScreenParams(client: PluginClientContext): boolean {
+  return openScreenApi(client) !== null;
+}

package/client/pill.tsx

@@ -7,6 +7,7 @@ import type {
 import { Icon } from "@getpaseo/plugin/client/react-native";
 import React, { useSyncExternalStore } from "react";
 import { readMetrics } from "../shared/contracts";
+import { openMachineScreen } from "./compat";
 import { createMachineCard } from "./pill-card";
 import { pillReading, type PillReading } from "../shared/pill";
 import { STATUS } from "../shared/viz";
@@ -72,7 +73,7 @@ interface TrackedAgent {
 export function contributePills(client: PluginClientContext) {
   const store = createReadingStore();
   const icon = createIcon(store);
-  const card = createMachineCard(() => client.openSurface("main"));
+  const card = createMachineCard(() => openMachineScreen(client));
   const pills = new Map<string, { workspaceId: string; registration: PluginButtonRegistration }>();
   let disposed = false;
   let inFlight = false;

package/client/status.tsx

@@ -1,11 +1,12 @@
 import { useRpc, type PluginSurfaceProps } from "@getpaseo/plugin/client";
 import { useQuery } from "@tanstack/react-query";
-import React, { useMemo, useState } from "react";
+import React, { useEffect, useMemo, useState } from "react";
 import { Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
 import { ColumnChart, Legend, Meter, Sparkbars, StackedColumnChart, StatTile } from "./charts";
 import { ServicesTab } from "./services";
 import { CleanupSection } from "./cleanup";
 import { DockerTab } from "./docker";
+import type { MachineScreenProps } from "./compat";
 import { ContextMenuProvider } from "./menu";
 import { readMetrics, type Metrics } from "../shared/contracts";
 import { formatBytes, formatDuration, formatMinutes, formatPercent } from "../shared/format";
@@ -444,7 +445,7 @@ function DetailCard({
 }
 
 
-type TabId = "overview" | "services" | "docker";
+export type TabId = "overview" | "services" | "docker";
 
 const TABS: readonly { id: TabId; title: string }[] = [
   { id: "overview", title: "Overview" },
@@ -452,15 +453,23 @@ const TABS: readonly { id: TabId; title: string }[] = [
   { id: "docker", title: "Docker" },
 ];
 
+/** `?tab=` from a 0.11 screen link; anything unknown, or no params at all, is the overview. */
+function tabFromParams(params: MachineScreenProps["params"]): TabId {
+  return TABS.find((entry) => entry.id === params?.tab)?.id ?? "overview";
+}
+
 /**
  * Only the selected tab is mounted. The services tab shells out to netstat, lsof
  * and docker on a timer, and mounting it in the background would keep that
  * running for a panel nobody is looking at.
  */
-export function MachineStatusSurface(props: PluginSurfaceProps) {
+export function MachineStatusSurface(props: MachineScreenProps) {
   const chrome: Chrome = { theme: props.theme, compact: props.layout.compact };
   const styles = useChromeStyles(chrome);
-  const [tab, setTab] = useState<TabId>("overview");
+  const linkedTab = tabFromParams(props.params);
+  const [tab, setTab] = useState<TabId>(linkedTab);
+  // Opening the already-open screen with another `tab` swaps params without a remount.
+  useEffect(() => setTab(linkedTab), [linkedTab]);
 
   return (
     <ContextMenuProvider chrome={chrome}>

package/index.client.tsx

@@ -1,20 +1,14 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { openMachineScreen, registerMachineScreen, supportsScreenParams } from "./client/compat";
 import { contributePills } from "./client/pill";
 import { MachineStatusSurface } from "./client/status";
 
 /**
- * The app half of the plugin: the Machine surface, the ways into it from the
+ * The app half of the plugin: the Machine screen, the ways into it from the
  * sidebar and the Command Center, and the load pill beside each agent's composer.
  */
 export default function contribute(client: PluginClientContext) {
-  client.addSurface("main", MachineStatusSurface);
-
-  client.addSidebarItem({
-    id: "main",
-    title: "Machine",
-    icon: "Activity",
-    surface: "main",
-  });
+  registerMachineScreen(client, MachineStatusSurface);
 
   client.addCommandCenterItem({
     id: "open-machine-status",
@@ -22,10 +16,35 @@ export default function contribute(client: PluginClientContext) {
     icon: "Activity",
     keywords: ["cpu", "memory", "disk", "swap", "battery", "thermal", "ports", "services"],
     context: "global",
-    onSelect({ openSurface }) {
-      openSurface("main");
+    onSelect(capabilities) {
+      openMachineScreen(capabilities);
     },
   });
 
+  // Straight to a tab needs screen params. On older apps these would open the
+  // overview under a misleading title, so they are not offered there.
+  if (supportsScreenParams(client)) {
+    client.addCommandCenterItem({
+      id: "open-machine-services",
+      title: "Machine: ports & services",
+      icon: "Network",
+      keywords: ["ports", "listening", "lsof", "dev server"],
+      context: "global",
+      onSelect(capabilities) {
+        openMachineScreen(capabilities, { tab: "services" });
+      },
+    });
+    client.addCommandCenterItem({
+      id: "open-machine-docker",
+      title: "Machine: Docker",
+      icon: "Container",
+      keywords: ["docker", "containers", "orbstack", "rancher"],
+      context: "global",
+      onSelect(capabilities) {
+        openMachineScreen(capabilities, { tab: "docker" });
+      },
+    });
+  }
+
   return contributePills(client);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-plugin-machine-status",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Machine dashboard, open ports and Docker control inside Paseo",
   "license": "MIT",
   "author": "dutchakdev",
@@ -15,20 +15,26 @@
     "macos",
     "docker"
   ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "preview": "tsx scripts/preview.ts"
+    "preview": "tsx scripts/preview.ts",
+    "check": "npm run typecheck && npm test"
   },
   "devDependencies": {
     "@getpaseo/client": "0.8.0",
     "@getpaseo/plugin": "0.8.0",
     "@getpaseo/protocol": "0.8.0",
     "@tanstack/react-query": "^5.90.11",
+    "@types/node": "22.20.5",
     "@types/react": "~19.2.0",
     "react": "19.1.0",
     "react-native": "0.81.5",
+    "semver": "7.8.5",
     "tsx": "^4.23.13",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
@@ -36,6 +42,7 @@
   },
   "files": [
     "paseo-plugin.json",
+    "OVERVIEW.md",
     "index.client.tsx",
     "index.server.ts",
     "client/",