@xpufx/paseo-top 0.4.3 → 0.4.5

package/package.json

@@ -2,25 +2,34 @@
   "name": "@xpufx/paseo-top",
   "private": false,
   "license": "MIT",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "scripts": {
     "stamp": "node -e \"import('./server/vendor/paseo-plugin-helper/version.ts').then(m => m.stampVersion({ targetFile: 'shared/version.ts' }))\"",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && npx tsx --test server/telemetry.test.ts client/pill-labels.test.ts client/turn-counter.test.ts client/telemetry-copy.test.ts client/multi-host.test.ts"
+    "test": "npm run typecheck && vitest run --config client/vitest.config.ts"
+  },
+  "dependencies": {
+    "@xpufx/paseo-plugin-ui": "^0.1.0"
   },
   "devDependencies": {
+    "paseo-plugin-ui-testing": "*",
     "@getpaseo/plugin": "^0.9.0",
     "@tanstack/react-query": "^5.90.11",
     "@types/react": "^19.0.10",
+    "@types/react-test-renderer": "^19.3.0",
     "react": "19.1.0",
     "react-native": "0.81.5",
+    "react-test-renderer": "^19.1.0",
     "typescript": "^5.9.3",
+    "vitest": "^3.0.0",
     "zod": "^4.4.3"
   },
   "files": [
     "paseo-plugin.json",
     "README.md",
+    "OVERVIEW.md",
     "LICENSE",
+    "screenshots",
     "index.client.tsx",
     "index.server.ts",
     "client",
@@ -30,6 +39,9 @@
     "!**/*.test.ts",
     "!**/*.test.tsx",
     "!**/*.test.mjs",
+    "!client/test-utils",
+    "!server/__node-test-shim.ts",
+    "!client/vitest.config.ts",
     "!**/.DS_Store"
   ],
   "repository": {

package/paseo-plugin.json

@@ -1,4 +1,6 @@
 {
   "id": "top",
+  "name": "Top",
+  "description": "Live host system and workspace monitor for the Paseo composer trackbar",
   "requirements": { "paseo": ">=0.9.0" }
 }

package/server/resources.ts

@@ -29,6 +29,91 @@ import {
 } from "../shared/resources";
 import { PLUGIN_VERSION } from "../shared/version";
 
+// --- Velocity & Context Pressure helpers -------------------------------------
+
+/** Thresholds for context pressure levels. */
+const CONTEXT_NORMAL_UPPER = 60; // <60% → normal
+const CONTEXT_WARNING_UPPER = 75; // 60-74% → warning, >=75% → high
+
+/**
+ * Compute live generation velocity (tokens per second).
+ *
+ * Formula: (outputTokens + reasoningTokens) / (durationMs / 1000)
+ *
+ * Returns 0 for:
+ * - zero or missing duration (< 50 ms threshold to avoid skewed averages)
+ * - missing output tokens
+ * - interrupted/canceled turns (prevents skewed averages on partial generations)
+ */
+export function computeTokensPerSecond(
+  outputTokens: number | undefined,
+  durationMs: number | undefined,
+  outcomeKind: string,
+): number | undefined {
+  if (outputTokens == null || !Number.isFinite(outputTokens)) return undefined;
+  if (outputTokens <= 0) return 0;
+
+  const dur = durationMs ?? undefined;
+  if (dur == null || !Number.isFinite(dur) || dur < 50) return 0;
+
+  // Interrupted/canceled turns with partial data yield 0 TPS.
+  if (outcomeKind === "canceled" || outcomeKind === "failed") return 0;
+
+  const durationSec = dur / 1000;
+  const rate = outputTokens / durationSec;
+  if (!Number.isFinite(rate) || rate <= 0) return 0;
+  return Math.round(rate * 100) / 100; // round to 2dp
+}
+
+/** Context pressure level based on utilization percentage. */
+type ContextPressureLevel = "normal" | "warning" | "high";
+
+/**
+ * Classify context pressure into discrete levels:
+ * - "normal": utilization < 60%
+ * - "warning": 60–74%
+ * - "high": >= 75% (amnesia risk)
+ *
+ * Returns undefined when context window info is absent.
+ */
+export function classifyContextPressure(
+  contextUsedTokens: number | undefined,
+  contextMaxTokens: number | undefined,
+): { level: ContextPressureLevel; pct: number } | undefined {
+  if (
+    contextUsedTokens == null ||
+    contextMaxTokens == null ||
+    contextMaxTokens <= 0
+  ) {
+    return undefined;
+  }
+
+  const pct = Math.min(100, Math.round((contextUsedTokens / contextMaxTokens) * 100));
+
+  let level: ContextPressureLevel;
+  if (pct >= CONTEXT_WARNING_UPPER) {
+    level = "high";
+  } else if (pct >= CONTEXT_NORMAL_UPPER) {
+    level = "warning";
+  } else {
+    level = "normal";
+  }
+
+  return { level, pct };
+}
+
+/** Spread context pressure fields into the telemetry object. */
+function computeContextPressure(
+  contextUsedTokens: number | undefined,
+  contextMaxTokens: number | undefined,
+): Pick<TopTimelineTelemetryData, "contextPressureLevel" | "contextUtilizationPct"> {
+  const result = classifyContextPressure(contextUsedTokens, contextMaxTokens);
+  return {
+    contextPressureLevel: result?.level,
+    contextUtilizationPct: result?.pct,
+  };
+}
+
 export const log = createPluginLogger("top", { version: PLUGIN_VERSION });
 
 log.info("Initialized host system resources monitor", { version: PLUGIN_VERSION });
@@ -437,6 +522,10 @@ export async function handleGetSystemResources(input?: {
       .filter((state) => effectiveEnabled.has(state.id)),
     lastTurn: lastTurnTelemetry,
     liveUsage: lastLiveUsage,
+    // Velocity data from the most recent turn telemetry.
+    tokensPerSecond: lastTurnTelemetry?.tokensPerSecond,
+    contextPressureLevel: lastTurnTelemetry?.contextPressureLevel,
+    contextUtilizationPct: lastTurnTelemetry?.contextUtilizationPct,
   };
 }
 
@@ -778,6 +867,15 @@ export async function collectTurnTelemetry(
     contextUsedTokens,
     contextMaxTokens,
     costUsd,
+    // Live generation velocity: (output + reasoning) / durationSec.
+    // Guard against zero-duration, missing fields, and interrupted turns.
+    tokensPerSecond: computeTokensPerSecond(
+      outputTokens,
+      durationMs,
+      outcome.kind,
+    ),
+    // Context pressure from the most recent turn's utilization.
+    ...computeContextPressure(contextUsedTokens, contextMaxTokens),
   };
   lastTurnTelemetry = data;
   return data;

package/server/vendor/paseo-plugin-helper/custom-pills.ts

@@ -11,6 +11,9 @@ import {
   parseNumericPillValue,
   formatPillDisplay,
 } from "../../../shared/vendor/paseo-plugin-helper/custom-pills";
+import type { FeatureModule, FeatureDisposer } from "../../../shared/vendor/paseo-plugin-helper/features";
+import type { PluginRpcContract } from "../../../shared/vendor/paseo-plugin-helper/rpc";
+
 
 
 /**
@@ -342,3 +345,70 @@ export class CustomPillPoller {
     }
   }
 }
+
+export interface CustomPillsFeatureOptions {
+  id?: string;
+  configDir?: string;
+  logger?: PluginLogger;
+  poller?: CustomPillPoller;
+  contracts?: {
+    get?: PluginRpcContract;
+    list?: PluginRpcContract;
+    run?: PluginRpcContract;
+  };
+  handlers?: {
+    get?: (input?: any) => Promise<any> | any;
+    list?: (input?: any) => Promise<any> | any;
+    run?: (input: any) => Promise<any> | any;
+  };
+  onMount?: (poller: CustomPillPoller) => void;
+  startPoller?: boolean;
+}
+
+/**
+ * Creates a reusable FeatureModule for declarative custom metric pills (#933).
+ */
+export function createCustomPillsFeature<TServerContext = any, TClientContext = any>(
+  options: CustomPillsFeatureOptions = {},
+): FeatureModule<TServerContext, TClientContext> {
+  const poller = options.poller ?? new CustomPillPoller({
+    configDir: options.configDir,
+    logger: options.logger,
+  });
+
+  const contractsRecord: Record<string, PluginRpcContract> = {};
+  if (options.contracts?.get) contractsRecord.get = options.contracts.get;
+  if (options.contracts?.list) contractsRecord.list = options.contracts.list;
+  if (options.contracts?.run) contractsRecord.run = options.contracts.run;
+
+  return {
+    id: options.id || "custom-pills",
+    contracts: contractsRecord,
+    contributeServer(server: any) {
+      if (options.startPoller !== false) {
+        void poller.start();
+      }
+      options.onMount?.(poller);
+
+      if (typeof server?.handle === "function") {
+        if (options.contracts?.get && options.handlers?.get) {
+          server.handle(options.contracts.get, options.handlers.get);
+        }
+        if (options.contracts?.list && options.handlers?.list) {
+          server.handle(options.contracts.list, options.handlers.list);
+        }
+        if (options.contracts?.run && options.handlers?.run) {
+          server.handle(options.contracts.run, options.handlers.run);
+        }
+      }
+
+      let stopped = false;
+      return () => {
+        if (stopped) return;
+        stopped = true;
+        poller.stop();
+      };
+    },
+  };
+}
+

package/server/vendor/paseo-plugin-helper/index.ts

@@ -16,3 +16,7 @@ export * from "./custom-pills";
 export * from "./rpc-guard";
 export * from "./agent";
 export * from "./workspace-beacon";
+export * from "./tickets";
+export * from "./storage-guard";
+export * from "./telemetry";
+

package/server/vendor/paseo-plugin-helper/logger.ts

@@ -46,28 +46,17 @@ export function isProductionEnv(env: NodeJS.ProcessEnv = process.env): boolean {
   return (env.NODE_ENV ?? "").trim().toLowerCase() === "production";
 }
 
-/**
- * True only when `NODE_ENV` is explicitly a development value
- * (`development`/`dev`). Unset, empty, `production`, and anything else
- * (e.g. `test`) all count as quiet, so a shipped plugin defaults to info
- * without any env var set.
- */
-export function isDevelopmentEnv(env: NodeJS.ProcessEnv = process.env): boolean {
-  const nodeEnv = (env.NODE_ENV ?? "").trim().toLowerCase();
-  return nodeEnv === "development" || nodeEnv === "dev";
-}
-
 /**
  * Default rule (documented for operators):
  * explicit `PASEO_PLUGIN_LOG_LEVEL`/`PASEO_LOG_LEVEL`/`PASEO_DEBUG` always wins;
- * otherwise quiet (`info`) — including when no env var is set at all, so a
- * shipped plugin never emits debug logs by default. Debug only when `NODE_ENV`
- * is explicitly a development value (`development`/`dev`).
+ * otherwise `info` in every environment — including `NODE_ENV=development`/`dev`
+ * and when no env var is set at all. Debug requires an explicit level; the
+ * environment name alone never lifts the floor.
  */
 export function resolveDefaultMinLevel(
   env: NodeJS.ProcessEnv = process.env,
 ): LogLevel {
-  return resolveMinLevelFromEnv(env) ?? (isDevelopmentEnv(env) ? "debug" : "info");
+  return resolveMinLevelFromEnv(env) ?? "info";
 }
 
 export interface PluginLoggerOptions {
@@ -90,7 +79,7 @@ export interface PluginLoggerOptions {
 
   /**
    * Minimum log level to print. Defaults to resolveDefaultMinLevel():
-   * info unless NODE_ENV is explicitly development (or an explicit level is set).
+   * info unless an explicit level is set via the environment.
    */
   minLevel?: LogLevel;
 

package/server/vendor/paseo-plugin-helper/mcp-injection.ts

@@ -4,6 +4,7 @@ export interface McpStdioInjectionConfig {
   args?: string[];
   env?: Record<string, string>;
   alwaysLoad?: boolean;
+  instructions?: string;
 }
 
 export interface McpHttpInjectionConfig {
@@ -11,6 +12,7 @@ export interface McpHttpInjectionConfig {
   url: string;
   headers?: Record<string, string>;
   alwaysLoad?: boolean;
+  instructions?: string;
 }
 
 export interface McpSseInjectionConfig {
@@ -18,6 +20,7 @@ export interface McpSseInjectionConfig {
   url: string;
   headers?: Record<string, string>;
   alwaysLoad?: boolean;
+  instructions?: string;
 }
 
 export type McpInjectionConfig =
@@ -71,15 +74,30 @@ export function registerMcpInjection(
   const { serverName, config, filter } = options;
   return server.before("agent.create", ({ request }: { request: AgentCreateInjectionRequest }) => {
     if (filter && !filter({ request })) return;
-    return {
+    const injectedConfig = { ...config };
+    if (injectedConfig.instructions === "") {
+      delete injectedConfig.instructions;
+    }
+    const composed: AgentCreateInjectionRequest = {
       ...request,
       config: {
         ...request.config,
         mcpServers: {
           ...(request.config.mcpServers ?? {}),
-          [serverName]: config,
+          [serverName]: injectedConfig,
         },
       },
     };
+    // Opt-in per server: only a config that sets `instructions` gets text
+    // composed into the agent. Absent means byte-identical passthrough.
+    if (typeof config.instructions !== "string" || config.instructions === "") return composed;
+    const base = typeof request.config.systemPrompt === "string" ? request.config.systemPrompt : "";
+    return {
+      ...composed,
+      config: {
+        ...composed.config,
+        systemPrompt: base.trim().length > 0 ? `${base}\n\n${config.instructions}` : config.instructions,
+      },
+    };
   });
 }

package/server/vendor/paseo-plugin-helper/plugins.ts

@@ -26,15 +26,54 @@ export interface ListPluginsOptions {
   forceRefresh?: boolean;
 }
 
+/** Normalized presence record returned to plugin code by `listPlugins(context)`. */
+export interface PluginPresence {
+  id: string;
+  status: string;
+  enabled: boolean;
+}
+
+/**
+ * Minimal structural view of the daemon plugin surface a plugin may reach
+ * through `context.paseo`. Current SDK `PaseoApi` exposes no plugins actions,
+ * so this stays optional and duck-typed; when absent the helper falls back to
+ * the daemon's existing `paseo plugin ls --json` query.
+ */
+export interface PaseoPluginsSurface {
+  list(): Promise<unknown>;
+}
+
+/**
+ * Handler/hook context shape plugin server code passes to the presence API.
+ * `paseo` stays `unknown` so the real `PluginHandlerContext` (whose `paseo` is
+ * the SDK `PaseoApi`) is assignable even though current SDK builds expose no
+ * plugins actions; the surface is duck-typed at call time.
+ */
+export interface PluginRegistryContext {
+  paseo?: unknown;
+}
+
+export interface PluginQueryOptions {
+  cacheTtlMs?: number;
+  forceRefresh?: boolean;
+}
+
+interface PresenceCache {
+  at: number;
+  plugins: PluginPresence[];
+}
+
 let cachedPlugins: PaseoPluginInfo[] | null = null;
 let lastFetchTime = 0;
+let cachedPresence: PresenceCache | null = null;
 
 /**
- * Clears the in-memory plugin list cache.
+ * Clears the in-memory plugin list and presence caches.
  */
 export function clearPluginCache(): void {
   cachedPlugins = null;
   lastFetchTime = 0;
+  cachedPresence = null;
 }
 
 /**
@@ -68,10 +107,30 @@ function readConfigPluginsFallback(): PaseoPluginInfo[] {
 }
 
 /**
- * Lists plugins from the Paseo daemon, with optional filtering and TTL caching.
- * Primary mechanism uses 'paseo plugin ls --json', with fallback to ~/.paseo/config.json.
+ * Queries the daemon's authoritative plugin list through the CLI RPC that the
+ * daemon already serves ('paseo plugin ls --json'). Returns null when the daemon
+ * is unreachable or answers with a non-array payload, so callers can choose
+ * their own fallback instead of parsing filesystem state.
+ */
+async function fetchDaemonPluginInfo(): Promise<PaseoPluginInfo[] | null> {
+  try {
+    const result = await safeSpawn("paseo", ["plugin", "ls", "--json"], { timeoutMs: 3000 });
+    if (result.code === 0 && result.stdout.trim()) {
+      const parsed: unknown = JSON.parse(result.stdout.trim());
+      return Array.isArray(parsed) ? (parsed as PaseoPluginInfo[]) : null;
+    }
+  } catch {
+    // Unreachable daemon / malformed payload: report absence, never throw.
+  }
+  return null;
+}
+
+/**
+ * Lists full plugin metadata from the Paseo daemon, with optional filtering and
+ * TTL caching. Primary mechanism uses 'paseo plugin ls --json', with fallback to
+ * ~/.paseo/config.json.
  */
-export async function listPlugins(options: ListPluginsOptions = {}): Promise<PaseoPluginInfo[]> {
+async function listPluginInfo(options: ListPluginsOptions = {}): Promise<PaseoPluginInfo[]> {
   const { filter = "all", cacheTtlMs = 5000, forceRefresh = false } = options;
   const now = Date.now();
 
@@ -79,23 +138,102 @@ export async function listPlugins(options: ListPluginsOptions = {}): Promise<Pas
     return applyFilter(cachedPlugins, filter);
   }
 
-  let plugins: PaseoPluginInfo[] = [];
+  const fromDaemon = await fetchDaemonPluginInfo();
+  const plugins = fromDaemon ?? readConfigPluginsFallback();
 
-  try {
-    const result = await safeSpawn("paseo", ["plugin", "ls", "--json"], { timeoutMs: 3000 });
-    if (result.code === 0 && result.stdout.trim()) {
-      plugins = JSON.parse(result.stdout.trim());
-    } else {
-      plugins = readConfigPluginsFallback();
+  cachedPlugins = plugins;
+  lastFetchTime = now;
+
+  return applyFilter(plugins, filter);
+}
+
+function isRegistryContext(value: unknown): value is PluginRegistryContext {
+  return !!value && typeof value === "object" && "paseo" in (value as Record<string, unknown>);
+}
+
+/** Coerces a daemon plugin list (SDK shape) into normalized presence records. */
+function normalizePresence(raw: unknown): PluginPresence[] {
+  if (!Array.isArray(raw)) return [];
+  const out: PluginPresence[] = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const rec = entry as Record<string, unknown>;
+    const id = typeof rec.id === "string" ? rec.id : null;
+    if (!id) continue;
+    const enabled = rec.enabled !== false;
+    const status =
+      typeof rec.status === "string" ? rec.status : enabled ? "unknown" : "disabled";
+    out.push({ id, status, enabled });
+  }
+  return out;
+}
+
+/**
+ * Resolves plugin presence through the sanctioned daemon channel. Prefers a
+ * `context.paseo.plugins.list()` SDK surface when one exists; otherwise falls
+ * back to the daemon's existing plugin-list RPC. Any failure — no context, no
+ * surface, unreachable daemon, malformed payload — resolves to `[]`.
+ *
+ * Only the daemon-fallback result is cached (the CLI spawn is the real cost);
+ * a caller-supplied context surface is always consulted fresh so different
+ * contexts never observe each other's cached presence.
+ */
+async function listPluginPresence(
+  context: PluginRegistryContext | null | undefined,
+  options: PluginQueryOptions = {},
+): Promise<PluginPresence[]> {
+  const { cacheTtlMs = 5000, forceRefresh = false } = options;
+  const now = Date.now();
+  const surface = readPluginsSurface(context?.paseo);
+
+  if (!surface) {
+    if (!forceRefresh && cachedPresence && now - cachedPresence.at < cacheTtlMs) {
+      return cachedPresence.plugins;
     }
+    const plugins = normalizePresence(await fetchDaemonPluginInfo());
+    cachedPresence = { at: now, plugins };
+    return plugins;
+  }
+
+  try {
+    return normalizePresence(await surface.list());
   } catch {
-    plugins = readConfigPluginsFallback();
+    return [];
   }
+}
 
-  cachedPlugins = plugins;
-  lastFetchTime = now;
+/** Duck-types `context.paseo.plugins.list()` without assuming the SDK shape. */
+function readPluginsSurface(paseo: unknown): PaseoPluginsSurface | null {
+  if (!paseo || typeof paseo !== "object") return null;
+  const plugins = (paseo as { plugins?: unknown }).plugins;
+  if (!plugins || typeof plugins !== "object") return null;
+  const list = (plugins as { list?: unknown }).list;
+  return typeof list === "function" ? (plugins as PaseoPluginsSurface) : null;
+}
 
-  return applyFilter(plugins, filter);
+/**
+ * Lists plugins. Called with a plugin/handler `context`, returns normalized
+ * presence records `{ id, status, enabled }` resolved through the daemon (see
+ * `listPluginPresence`); absence tolerates to `[]`. Called without a context,
+ * returns the legacy full `PaseoPluginInfo[]` metadata list.
+ */
+export function listPlugins(
+  context: PluginRegistryContext | null | undefined,
+  options?: PluginQueryOptions,
+): Promise<PluginPresence[]>;
+export function listPlugins(options?: ListPluginsOptions): Promise<PaseoPluginInfo[]>;
+export async function listPlugins(
+  contextOrOptions?: PluginRegistryContext | ListPluginsOptions | null,
+  maybeOptions: PluginQueryOptions = {},
+): Promise<PluginPresence[] | PaseoPluginInfo[]> {
+  // A registry context is an object carrying `paseo`, or an explicitly passed
+  // null context (the "caller has no context" case, which tolerates to []). A
+  // bare option object (no `paseo` key), or no argument at all, stays on the
+  // legacy full-metadata path.
+  if (isRegistryContext(contextOrOptions) || contextOrOptions === null) {
+    return listPluginPresence(contextOrOptions, maybeOptions);
+  }
+  return listPluginInfo(contextOrOptions ?? {});
 }
 
 function applyFilter(plugins: PaseoPluginInfo[], filter: PluginStatusFilter): PaseoPluginInfo[] {
@@ -128,13 +266,40 @@ export async function getPluginInfo(
 
 /**
  * Checks whether a plugin is installed in Paseo.
+ *
+ * Two forms:
+ * - `isPluginInstalled(pluginId, options?)` — legacy metadata query: true when
+ *   the plugin appears in the full plugin list at all.
+ * - `isPluginInstalled(context, id, options?)` — presence query: true only when
+ *   the plugin is usable (present, enabled, and status "running"). Anything else
+ *   — absent, disabled, failed, unknown — resolves to false. A missing daemon
+ *   surface tolerates to false, never throws.
  */
-export async function isPluginInstalled(
+export function isPluginInstalled(
   pluginId: string,
-  options?: { cacheTtlMs?: number; forceRefresh?: boolean },
+  options?: PluginQueryOptions,
+): Promise<boolean>;
+export function isPluginInstalled(
+  context: PluginRegistryContext | null | undefined,
+  id: string,
+  options?: PluginQueryOptions,
+): Promise<boolean>;
+export async function isPluginInstalled(
+  contextOrId: PluginRegistryContext | string | null | undefined,
+  idOrOptions?: string | PluginQueryOptions,
+  maybeOptions: PluginQueryOptions = {},
 ): Promise<boolean> {
-  const info = await getPluginInfo(pluginId, options);
-  return info !== null;
+  if (typeof contextOrId === "string") {
+    const info = await getPluginInfo(contextOrId, idOrOptions as PluginQueryOptions | undefined);
+    return info !== null;
+  }
+
+  const id = typeof idOrOptions === "string" ? idOrOptions : "";
+  if (!id) return false;
+
+  const plugins = await listPluginPresence(contextOrId, maybeOptions);
+  const match = plugins.find((p) => p.id === id);
+  return !!match && match.enabled && match.status === "running";
 }
 
 /**

package/server/vendor/paseo-plugin-helper/rpc-guard.ts

@@ -1,4 +1,4 @@
-import { withTimeout, TimeoutError } from "../../../shared/vendor/paseo-plugin-helper/async";
+import { withTimeout, isTimeoutError } from "../../../shared/vendor/paseo-plugin-helper/async";
 
 export interface RpcGuardOptions<T> {
   timeoutMs?: number;
@@ -40,7 +40,7 @@ export function guardRpcHandler<TInput, TOutput>(
         "RPC handler",
       );
     } catch (err) {
-      if (err instanceof TimeoutError) {
+      if (isTimeoutError(err)) {
         options.onTimeout?.({ timeoutMs, inflight });
       }
       throw err;