@xpufx/paseo-top 0.4.3 → 0.4.5

package/shared/helper-version.ts

@@ -0,0 +1,20 @@
+// Declared paseo-plugin-helper expectation for top.
+//
+// This plugin carries a committed vendored helper tree, but its bare
+// `paseo-plugin-helper/<tree>` imports still resolve through this checkout's
+// tsconfig `paths` alias into ../../packages/paseo-plugin-helper/src, so part
+// of what it runs comes from the checkout rather than from the copy it carries.
+// Resolution is therefore "checkout", and this file records what that resolution is
+// supposed to be, so scripts/helper-resolution.test.mjs can contradict it if the
+// two ever disagree (#633, #649).
+//
+// HELPER_VERSION is the helper's own package.json `version` — the same value the
+// vendored READMEs pin, not a scheme invented for this plugin.
+// HELPER_REVISION is a content digest of packages/paseo-plugin-helper/src at
+// stamp time. It is the authoritative check, and it is preferred over the
+// checkout sha in shared/version.ts because a squash-merge deletes the very
+// commit that sha names, orphaning it in every clean clone while it still
+// resolves on any machine holding the branch worktree.
+export const HELPER_VERSION = "0.4.0-beta.12";
+export const HELPER_SERVED_FROM = "checkout";
+export const HELPER_REVISION = "sha256:8ac23e85d016";

package/shared/multi-host.ts

@@ -1,4 +1,4 @@
-import { TimeoutError, withTimeout } from "./vendor/paseo-plugin-helper/index";
+import { isTimeoutError, withTimeout } from "./vendor/paseo-plugin-helper/index";
 
 /**
  * Bounded multi-host fleet polling state machine.
@@ -133,132 +133,74 @@ export function aggregateFleet(
   return aggregate;
 }
 
-export class MultiHostPoller {
-  static readonly DEFAULT_INTERVAL_MS = 15_000;
-  static readonly DEFAULT_TIMEOUT_MS = 4_000;
+export const DEFAULT_MULTI_HOST_INTERVAL_MS = 15_000;
+export const DEFAULT_MULTI_HOST_TIMEOUT_MS = 4_000;
 
-  private readonly options: Required<
-    Pick<MultiHostPollerOptions, "timeoutMs" | "intervalMs" | "now">
-  > &
-    Pick<MultiHostPollerOptions, "acquire" | "onUpdate">;
-  private readonly snapshots = new Map<string, FleetHostSnapshot>();
-  private readonly clients = new Map<string, FleetHostClient>();
-  private readonly inFlight = new Set<string>();
-  /** Bumped on any connection transition so in-flight results are discarded. */
-  private readonly generation = new Map<string, number>();
-  private timer: ReturnType<typeof setInterval> | null = null;
-  private running = false;
-  private tickInFlight = false;
-  private disposed = false;
-
-  constructor(options: MultiHostPollerOptions) {
-    this.options = {
-      timeoutMs: options.timeoutMs ?? MultiHostPoller.DEFAULT_TIMEOUT_MS,
-      intervalMs: options.intervalMs ?? MultiHostPoller.DEFAULT_INTERVAL_MS,
-      now: options.now ?? (() => Date.now()),
-      acquire: options.acquire,
-      onUpdate: options.onUpdate,
-    };
-  }
-
-  /** Reconcile the live host list, releasing clients across transitions. */
-  setHosts(hosts: readonly FleetHostInput[]): void {
-    if (this.disposed) return;
-    const next = new Map(hosts.map((host) => [host.serverId, host]));
-
-    for (const serverId of [...this.snapshots.keys()]) {
-      if (!next.has(serverId)) {
-        this.bumpGeneration(serverId);
-        this.disposeClient(serverId);
-        this.snapshots.delete(serverId);
-        this.inFlight.delete(serverId);
-      }
-    }
-
-    for (const host of next.values()) {
-      const existing = this.snapshots.get(host.serverId);
-      if (!existing) {
-        this.snapshots.set(host.serverId, {
-          serverId: host.serverId,
-          label: host.label,
-          connectionStatus: host.status,
-          status: fleetStatusFor(host.status),
-          latencyMs: null,
-          lastUpdatedAt: null,
-          staleAt: null,
-          error: null,
-          counts: null,
-        });
-        continue;
-      }
-      const transitioned = existing.connectionStatus !== host.status;
-      if (transitioned) {
-        // A status change (including reconnect/failover) invalidates the
-        // borrowed client; reacquire on the next probe.
-        this.bumpGeneration(host.serverId);
-        this.disposeClient(host.serverId);
-        existing.connectionStatus = host.status;
-        existing.status = fleetStatusFor(host.status);
-        if (host.status !== "online") {
-          // Disconnected hosts keep no counts; only a `stale` probe retains
-          // its last-known snapshot as a deliberate "unresponsive" state.
-          existing.staleAt = null;
-          existing.counts = null;
-        }
-      }
-      existing.label = host.label;
-    }
+export interface MultiHostPoller {
+  setHosts(hosts: readonly FleetHostInput[]): void;
+  start(): void;
+  stop(): void;
+  pollOnce(): Promise<void>;
+  getSnapshots(): FleetHostSnapshot[];
+  dispose(): void;
+}
 
-    this.emit();
+/**
+ * Closure-based on purpose: plugin client bundles are evaluated by Hermes from
+ * source, where a `class` expression binds as `undefined`. A class here made the
+ * Fleet tab crash with "Cannot read property 'prototype' of undefined"
+ * (#1066, #510). Never use `class` in client-reachable code.
+ */
+export function createMultiHostPoller(opts: MultiHostPollerOptions): MultiHostPoller {
+  const options = {
+    timeoutMs: opts.timeoutMs ?? DEFAULT_MULTI_HOST_TIMEOUT_MS,
+    intervalMs: opts.intervalMs ?? DEFAULT_MULTI_HOST_INTERVAL_MS,
+    now: opts.now ?? (() => Date.now()),
+    acquire: opts.acquire,
+    onUpdate: opts.onUpdate,
+  };
+  const snapshots = new Map<string, FleetHostSnapshot>();
+  const clients = new Map<string, FleetHostClient>();
+  const inFlight = new Set<string>();
+  /** Bumped on any connection transition so in-flight results are discarded. */
+  const generation = new Map<string, number>();
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let running = false;
+  let tickInFlight = false;
+  let disposed = false;
+
+  function currentGeneration(serverId: string): number {
+    return generation.get(serverId) ?? 0;
   }
-
-  /** Start the immediate poll plus the fixed-cadence loop. */
-  start(): void {
-    if (this.disposed || this.running) return;
-    this.running = true;
-    void this.pollOnce();
-    this.timer = setInterval(() => void this.pollOnce(), this.options.intervalMs);
+  function bumpGeneration(serverId: string): void {
+    generation.set(serverId, currentGeneration(serverId) + 1);
   }
-
-  stop(): void {
-    this.running = false;
-    if (this.timer !== null) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
+  function getSnapshots(): FleetHostSnapshot[] {
+    return sortFleetSnapshots([...snapshots.values()]);
   }
-
-  /** Run one bounded pass over all hosts. Safe to await in tests. */
-  async pollOnce(): Promise<void> {
-    if (this.disposed || this.tickInFlight) return;
-    this.tickInFlight = true;
-    try {
-      await Promise.all(
-        [...this.snapshots.keys()].map((serverId) => this.probeHost(serverId)),
-      );
-    } finally {
-      this.tickInFlight = false;
-      this.emit();
-    }
+  function emit(): void {
+    options.onUpdate?.(getSnapshots());
   }
-
-  getSnapshots(): FleetHostSnapshot[] {
-    return sortFleetSnapshots([...this.snapshots.values()]);
+  function acquireClient(serverId: string): FleetHostClient {
+    const existing = clients.get(serverId);
+    if (existing) return existing;
+    const client = options.acquire(serverId);
+    clients.set(serverId, client);
+    return client;
   }
-
-  dispose(): void {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.stop();
-    for (const serverId of [...this.clients.keys()]) {
-      this.disposeClient(serverId);
+  function disposeClient(serverId: string): void {
+    const client = clients.get(serverId);
+    if (!client) return;
+    clients.delete(serverId);
+    try {
+      void client.dispose();
+    } catch {
+      // A released borrowed client may already be disposed; ignore.
     }
-    this.snapshots.clear();
-    this.inFlight.clear();
   }
 
-  private async probeHost(serverId: string): Promise<void> {
-    const snapshot = this.snapshots.get(serverId);
+  async function probeHost(serverId: string): Promise<void> {
+    const snapshot = snapshots.get(serverId);
     if (!snapshot) return;
 
     if (snapshot.connectionStatus !== "online") {
@@ -267,75 +209,134 @@ export class MultiHostPoller {
         snapshot.connectionStatus === "error" ? "Host connection error" : null;
       return;
     }
-    if (this.inFlight.has(serverId)) return;
+    if (inFlight.has(serverId)) return;
 
-    this.inFlight.add(serverId);
-    const generation = this.currentGeneration(serverId);
-    const startedAt = this.options.now();
-    let timedOut = false;
+    inFlight.add(serverId);
+    const startGeneration = currentGeneration(serverId);
+    const startedAt = options.now();
     try {
-      const client = this.acquireClient(serverId);
+      const client = acquireClient(serverId);
       const counts = await withTimeout(
         client.readCounts(),
-        this.options.timeoutMs,
+        options.timeoutMs,
         `fleet probe ${snapshot.label}`,
       );
-      if (this.currentGeneration(serverId) !== generation) return;
+      if (currentGeneration(serverId) !== startGeneration) return;
       snapshot.status = "online";
       snapshot.counts = counts;
-      snapshot.latencyMs = this.options.now() - startedAt;
-      snapshot.lastUpdatedAt = this.options.now();
+      snapshot.latencyMs = options.now() - startedAt;
+      snapshot.lastUpdatedAt = options.now();
       snapshot.staleAt = null;
       snapshot.error = null;
     } catch (cause) {
-      if (this.currentGeneration(serverId) !== generation) return;
-      timedOut = cause instanceof TimeoutError;
-      if (timedOut) {
+      if (currentGeneration(serverId) !== startGeneration) return;
+      if (isTimeoutError(cause)) {
         // Unresponsive: mark stale with a timestamp and keep the borrowed
         // client. The next 15s tick is the only retry.
         snapshot.status = "stale";
-        snapshot.staleAt = this.options.now();
+        snapshot.staleAt = options.now();
         snapshot.error = "Timed out";
       } else {
         // A released/replaced connection surfaces here; drop the client so the
         // next probe reacquires a fresh one.
         snapshot.status = "error";
         snapshot.error = errorMessage(cause);
-        this.disposeClient(serverId);
+        disposeClient(serverId);
       }
     } finally {
-      this.inFlight.delete(serverId);
+      inFlight.delete(serverId);
     }
   }
 
-  private acquireClient(serverId: string): FleetHostClient {
-    const existing = this.clients.get(serverId);
-    if (existing) return existing;
-    const client = this.options.acquire(serverId);
-    this.clients.set(serverId, client);
-    return client;
-  }
-
-  private disposeClient(serverId: string): void {
-    const client = this.clients.get(serverId);
-    if (!client) return;
-    this.clients.delete(serverId);
+  async function pollOnce(): Promise<void> {
+    if (disposed || tickInFlight) return;
+    tickInFlight = true;
     try {
-      void client.dispose();
-    } catch {
-      // A released borrowed client may already be disposed; ignore.
+      await Promise.all([...snapshots.keys()].map((serverId) => probeHost(serverId)));
+    } finally {
+      tickInFlight = false;
+      emit();
     }
   }
 
-  private currentGeneration(serverId: string): number {
-    return this.generation.get(serverId) ?? 0;
-  }
+  function setHosts(hosts: readonly FleetHostInput[]): void {
+    if (disposed) return;
+    const next = new Map(hosts.map((host) => [host.serverId, host]));
+
+    for (const serverId of [...snapshots.keys()]) {
+      if (!next.has(serverId)) {
+        bumpGeneration(serverId);
+        disposeClient(serverId);
+        snapshots.delete(serverId);
+        inFlight.delete(serverId);
+      }
+    }
+
+    for (const host of next.values()) {
+      const existing = snapshots.get(host.serverId);
+      if (!existing) {
+        snapshots.set(host.serverId, {
+          serverId: host.serverId,
+          label: host.label,
+          connectionStatus: host.status,
+          status: fleetStatusFor(host.status),
+          latencyMs: null,
+          lastUpdatedAt: null,
+          staleAt: null,
+          error: null,
+          counts: null,
+        });
+        continue;
+      }
+      const transitioned = existing.connectionStatus !== host.status;
+      if (transitioned) {
+        // A status change (including reconnect/failover) invalidates the
+        // borrowed client; reacquire on the next probe.
+        bumpGeneration(host.serverId);
+        disposeClient(host.serverId);
+        existing.connectionStatus = host.status;
+        existing.status = fleetStatusFor(host.status);
+        if (host.status !== "online") {
+          // Disconnected hosts keep no counts; only a `stale` probe retains
+          // its last-known snapshot as a deliberate "unresponsive" state.
+          existing.staleAt = null;
+          existing.counts = null;
+        }
+      }
+      existing.label = host.label;
+    }
 
-  private bumpGeneration(serverId: string): void {
-    this.generation.set(serverId, this.currentGeneration(serverId) + 1);
+    emit();
   }
 
-  private emit(): void {
-    this.options.onUpdate?.(this.getSnapshots());
+  function stop(): void {
+    running = false;
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
   }
+
+  return {
+    setHosts,
+    /** Start the immediate poll plus the fixed-cadence loop. */
+    start() {
+      if (disposed || running) return;
+      running = true;
+      void pollOnce();
+      timer = setInterval(() => void pollOnce(), options.intervalMs);
+    },
+    stop,
+    /** Run one bounded pass over all hosts. Safe to await in tests. */
+    pollOnce,
+    getSnapshots,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stop();
+      for (const serverId of [...clients.keys()]) disposeClient(serverId);
+      snapshots.clear();
+      inFlight.clear();
+    },
+  };
 }

package/shared/resources.ts

@@ -3,6 +3,9 @@ import {
   defineSettingsContract,
   type RpcOutput,
   type CustomPillState,
+  type MetricThresholds,
+  formatBytes,
+  formatUptime,
 } from "./vendor/paseo-plugin-helper/index";
 import { z } from "zod";
 
@@ -142,6 +145,12 @@ export const topTimelineTelemetrySchema = z.object({
   contextUsedTokens: z.number().optional(),
   contextMaxTokens: z.number().optional(),
   costUsd: z.number().optional(),
+  /** Tokens per second of generation (output + reasoning / durationSec). Zero for zero-duration or interrupted turns. */
+  tokensPerSecond: z.number().optional(),
+  /** Context pressure level: "normal" (<60%), "warning" (60-74%), "high" (>=75%). */
+  contextPressureLevel: z.enum(["normal", "warning", "high"]).optional(),
+  /** Context utilization percentage (0-100). */
+  contextUtilizationPct: z.number().optional(),
 });
 export type TopTimelineTelemetryData = z.infer<typeof topTimelineTelemetrySchema>;
 
@@ -177,6 +186,12 @@ export const getSystemResourcesRpc = defineContract({
     customPills: z.array(CustomPillStateSchema).optional(),
     lastTurn: topTimelineTelemetrySchema.nullable().optional(),
     liveUsage: liveUsageSchema.nullable().optional(),
+    /** Tokens per second of generation from the most recent turn. */
+    tokensPerSecond: z.number().optional(),
+    /** Context pressure level from the most recent turn. */
+    contextPressureLevel: z.enum(["normal", "warning", "high"]).optional(),
+    /** Context utilization percentage from the most recent turn. */
+    contextUtilizationPct: z.number().optional(),
   }),
 });
 
@@ -204,6 +219,7 @@ export const MetricIdSchema = z.enum([
   "tokens",
   "tools",
   "turns",
+  "velocity",
 ]);
 export type MetricId = z.infer<typeof MetricIdSchema>;
 
@@ -223,6 +239,7 @@ export const METRIC_IDS: readonly MetricId[] = [
   "tokens",
   "tools",
   "turns",
+  "velocity",
 ];
 
 export const CORE_TIMELINE_METRICS: readonly MetricId[] = [
@@ -233,6 +250,7 @@ export const CORE_TIMELINE_METRICS: readonly MetricId[] = [
   "agent_id",
   "changes",
   "tokens",
+  "velocity",
 ];
 
 export const DEFAULT_METRIC_SURFACES: Record<MetricId, SurfaceTarget> = {
@@ -251,6 +269,7 @@ export const DEFAULT_METRIC_SURFACES: Record<MetricId, SurfaceTarget> = {
   tokens: "timeline",
   tools: "timeline",
   turns: "none",
+  velocity: "both",
 };
 
 export interface MetricDefinition {
@@ -263,6 +282,12 @@ export interface MetricDefinition {
   pillOnly?: boolean;
 }
 
+/** Context pressure thresholds matching the velocity pill's bloat logic. */
+export const CONTEXT_PRESSURE_THRESHOLDS: Record<string, number> = {
+  normalUpper: 60,
+  warningUpper: 75,
+};
+
 export const METRIC_DEFINITIONS: MetricDefinition[] = [
   {
     id: "cpu_ram",
@@ -366,6 +391,14 @@ export const METRIC_DEFINITIONS: MetricDefinition[] = [
     icon: "Repeat",
     shortLabel: "turns",
   },
+  {
+    id: "velocity",
+    title: "Generation Velocity",
+    description: "Live tokens-per-second tachometer with cache hit rate and context pressure",
+    icon: "Zap",
+    shortLabel: "tps",
+    core: true,
+  },
 ];
 
 export function isPillEnabled(target?: SurfaceTarget): boolean {
@@ -481,6 +514,7 @@ export const TIMELINE_RENDERED_METRICS: readonly MetricId[] = [
   "tokens",
   "tools",
   "turns",
+  "velocity",
 ];
 
 export interface LegacyFlagView {
@@ -549,6 +583,116 @@ export function legacyFlagView(settings: {
   };
 }
 
+// --- Canonical metric thresholds -------------------------------------------
+
+/**
+ * Single source of truth for CPU/RAM warning/danger color thresholds. The
+ * pill, the dashboard surface, and the timeline card all resolve through
+ * these constants so a metric never changes color depending on where it is
+ * displayed (pill.tsx and telemetry.tsx used to carry divergent copies).
+ */
+export const CPU_THRESHOLDS: MetricThresholds = { warning: 60, danger: 85 };
+export const MEM_THRESHOLDS: MetricThresholds = { warning: 70, danger: 85 };
+
+// --- Tabs -------------------------------------------------------------------
+
+export interface TopTabItem {
+  id: string;
+  label: string;
+  shortLabel: string;
+  icon: string;
+}
+
+const SYSTEM_TAB: TopTabItem = {
+  id: "system",
+  label: "System",
+  shortLabel: "System",
+  icon: "Activity",
+};
+const PERMISSIONS_TAB: TopTabItem = {
+  id: "permissions",
+  label: "Permissions",
+  shortLabel: "Permissions",
+  icon: "ShieldCheck",
+};
+const SETTINGS_TAB: TopTabItem = {
+  id: "settings",
+  label: "Settings",
+  shortLabel: "Settings",
+  icon: "Sliders",
+};
+const ABOUT_TAB: TopTabItem = { id: "about", label: "About", shortLabel: "About", icon: "Info" };
+
+/** Sidebar dashboard tabs (client/surface.tsx). */
+export const SURFACE_TABS: readonly TopTabItem[] = [
+  { ...SYSTEM_TAB, label: "Activity", shortLabel: "Activity" },
+  { id: "fleet", label: "Fleet", shortLabel: "Fleet", icon: "Server" },
+  PERMISSIONS_TAB,
+  SETTINGS_TAB,
+  ABOUT_TAB,
+];
+
+/** Pill modal tabs (client/pill.tsx). */
+export const MODAL_TABS: readonly TopTabItem[] = [
+  SYSTEM_TAB,
+  { id: "context", label: "Workspace", shortLabel: "Workspace", icon: "GitBranch" },
+  PERMISSIONS_TAB,
+  SETTINGS_TAB,
+  ABOUT_TAB,
+];
+
+// --- About section extras ---------------------------------------------------
+
+/**
+ * Host facts for the About tab. Shared verbatim by the dashboard surface and
+ * the pill modal so the two About sections cannot drift.
+ */
+export function aboutExtraItems(
+  data: SystemResources | undefined,
+): Array<{ label: string; value: string; copyable?: boolean }> {
+  return [
+    {
+      label: "Host Platform",
+      value: data?.platform ? `${data.platform} (${data.arch ?? "unknown"})` : "Linux",
+      copyable: true,
+    },
+    { label: "Host Name", value: data?.hostname ?? "localhost", copyable: true },
+    { label: "CPU Model", value: data?.cpuModel ?? "unknown", copyable: true },
+    { label: "CPU Cores", value: `${data?.cpuCores ?? 0} cores` },
+    {
+      label: "Total Memory",
+      value: data?.memoryTotalBytes ? formatBytes(data.memoryTotalBytes) : "unknown",
+    },
+    {
+      label: "Host Uptime",
+      value: data?.uptimeSeconds ? formatUptime(data.uptimeSeconds) : "unknown",
+    },
+  ];
+}
+
+// --- Enabled-flag OR chain ---------------------------------------------------
+
+/**
+ * The legacy pill-flag OR chain, formerly copy-pasted at every call site that
+ * asks "is any pill item enabled" (pill view, modal settings, multiple-mode
+ * sync). MCP is presence-gated separately, so it is not part of the base
+ * chain — callers OR it in with their own MCP resolution.
+ */
+export function hasAnyLegacyPillFlagEnabled(flags: LegacyFlagView): boolean {
+  return (
+    flags.showCpuRam ||
+    flags.showBranch ||
+    flags.showWorktree ||
+    flags.showAgentTitle ||
+    flags.showAgent ||
+    flags.showAgentProvider ||
+    flags.showAgentActivity ||
+    flags.showAgentId ||
+    flags.showLoad ||
+    flags.showUptime
+  );
+}
+
 /**
  * Migrates legacy boolean toggles and single recordTurnTelemetry switch into the
  * per-metric SurfaceTarget model: Record<MetricId, "pill" | "timeline" | "both" | "none">.
@@ -603,6 +747,7 @@ export function migrateLegacyMetricSurfaces(raw: Record<string, unknown>): Recor
     tokens: false,
     tools: false,
     turns: false,
+    velocity: false,
   };
 
   const result: Record<MetricId, SurfaceTarget> = { ...DEFAULT_METRIC_SURFACES };
@@ -654,7 +799,7 @@ export const TopSettingsSchema = z.preprocess(
     recordTurnTelemetry: z.boolean().optional(),
     timelineCadence: z.number().min(0).max(10).default(1),
     intervalSeconds: z.number().min(1).max(60).default(3),
-    defaultTab: z.enum(["system", "context", "settings", "about"]).default("system"),
+    defaultTab: z.enum(["system", "context", "permissions", "settings", "about"]).default("system"),
   })
 );
 

package/shared/vendor/paseo-plugin-helper/async.ts

@@ -1,11 +1,18 @@
-export class TimeoutError extends Error {
+// NOTE: no `class` here. Hermes eval of plugin client bundles binds class
+// expressions as `undefined`, so errors are plain Error objects with a brand.
+export interface TimeoutError extends Error {
   readonly timeoutMs: number;
+}
 
-  constructor(message: string, timeoutMs: number) {
-    super(message);
-    this.name = "TimeoutError";
-    this.timeoutMs = timeoutMs;
-  }
+export function createTimeoutError(message: string, timeoutMs: number): TimeoutError {
+  const err = new Error(message) as Error & { timeoutMs: number };
+  err.name = "TimeoutError";
+  err.timeoutMs = timeoutMs;
+  return err;
+}
+
+export function isTimeoutError(e: unknown): e is TimeoutError {
+  return e instanceof Error && e.name === "TimeoutError";
 }
 
 /**
@@ -21,7 +28,7 @@ export async function withTimeout<T>(
   let timer: any;
   const timeoutPromise = new Promise<never>((_, reject) => {
     timer = setTimeout(() => {
-      reject(new TimeoutError(`${label} timed out after ${timeoutMs}ms`, timeoutMs));
+      reject(createTimeoutError(`${label} timed out after ${timeoutMs}ms`, timeoutMs));
     }, timeoutMs);
   });