@xpufx/paseo-x-comms 0.3.0

package/shared/registry.ts

@@ -0,0 +1,366 @@
+import { defineRpc } from "paseo-plugin-helper/shared";
+import { z } from "zod";
+
+const DaemonEntrySchema = z.object({
+  name: z.string(),
+  value: z.string(),
+  valid: z.boolean(),
+  error: z.string().nullable(),
+});
+
+export const registryReadRpc = defineRpc({
+  name: "registry.read",
+  input: z.object({}),
+  output: z.object({
+    registryPath: z.string(),
+    exists: z.boolean(),
+    validJson: z.boolean(),
+    parseError: z.string().nullable(),
+    daemons: z.array(DaemonEntrySchema.extend({ serverId: z.string().nullable(), hostname: z.string().nullable() })),
+  }),
+});
+
+export const daemonAddRpc = defineRpc({
+  name: "daemon.add",
+  input: z.object({
+    name: z.string().min(1).max(64),
+    value: z.string().min(1).max(512),
+  }),
+  output: z.object({
+    saved: z.boolean(),
+    error: z.string().nullable(),
+    registryPath: z.string(),
+    daemons: z.array(DaemonEntrySchema),
+  }),
+});
+
+export const daemonUpdateRpc = defineRpc({
+  name: "daemon.update",
+  input: z.object({
+    // `name` is the current key; `rename`/`value` are the optional new values.
+    name: z.string().min(1).max(64),
+    rename: z.string().min(1).max(64).optional(),
+    value: z.string().min(1).max(512).optional(),
+  }),
+  output: z.object({
+    saved: z.boolean(),
+    error: z.string().nullable(),
+    registryPath: z.string(),
+    daemons: z.array(DaemonEntrySchema),
+  }),
+});
+
+export const daemonRemoveRpc = defineRpc({
+  name: "daemon.remove",
+  input: z.object({
+    name: z.string().min(1).max(64),
+  }),
+  output: z.object({
+    saved: z.boolean(),
+    error: z.string().nullable(),
+    registryPath: z.string(),
+    daemons: z.array(DaemonEntrySchema),
+  }),
+});
+
+export const daemonHealthRpc = defineRpc({
+  name: "daemon.health",
+  input: z.object({}),
+  output: z.object({
+    results: z.array(
+      z.object({
+        name: z.string(),
+        reachable: z.boolean(),
+        error: z.string().nullable(),
+        agentCount: z.number().nullable(),
+      }),
+    ),
+  }),
+});
+
+/**
+ * Live per-peer probe for the known-daemon surface (#7). One entry per
+ * registry daemon; each carries its own reachability so an unreachable host
+ * never fails the whole list. Identity/relay fields come from the peer's own
+ * `daemon.get_status`; the hub relationship is best-effort and stays null when
+ * the peer does not support it.
+ */
+export const peerStatusRpc = defineRpc({
+  name: "peer.status",
+  input: z.object({}),
+  output: z.object({
+    results: z.array(
+      z.object({
+        name: z.string(),
+        value: z.string(),
+        valid: z.boolean(),
+        reachable: z.boolean(),
+        error: z.string().nullable(),
+        transport: z.enum(["relay", "direct", "unknown"]),
+        // Identity from the peer's own daemon.get_status (handshake serverId
+        // is the fallback when the status payload omits it).
+        serverId: z.string().nullable(),
+        hostname: z.string().nullable(),
+        version: z.string().nullable(),
+        pid: z.number().nullable(),
+        listen: z.string().nullable(),
+        relayEnabled: z.boolean().nullable(),
+        relayEndpoint: z.string().nullable(),
+        providerCount: z.number().nullable(),
+        providersAvailable: z.number().nullable(),
+        hubState: z.string().nullable(),
+        hubDaemonId: z.string().nullable(),
+        hubOrigin: z.string().nullable(),
+        hubLastError: z.string().nullable(),
+      }),
+    ),
+  }),
+});
+
+export const serverStatusRpc = defineRpc({
+  name: "server.status",
+  input: z.object({}),
+  output: z.object({
+    installPath: z.string(),
+    installed: z.boolean(),
+    configured: z.boolean(),
+    version: z.string().nullable(),
+    syntaxOk: z.boolean(),
+    error: z.string().nullable(),
+  }),
+});
+
+export const introspectAgentsRpc = defineRpc({
+  name: "agents.introspect",
+  input: z.object({}),
+  output: z.object({
+    daemons: z.array(
+      z.object({
+        name: z.string(),
+        reachable: z.boolean(),
+        error: z.string().nullable(),
+        projects: z.array(
+          z.object({
+            project: z.string(),
+            workspaces: z.array(
+              z.object({
+                name: z.string(),
+                agents: z.array(
+                  z.object({
+                    agentId: z.string(),
+                    shortId: z.string(),
+                    name: z.string(),
+                    status: z.string(),
+                  }),
+                ),
+              }),
+            ),
+          }),
+        ),
+      }),
+    ),
+  }),
+});
+
+export const introduceAgentsRpc = defineRpc({
+  name: "agents.introduce",
+  input: z.object({
+    first: z.object({ daemon: z.string(), agentId: z.string(), shortId: z.string(), name: z.string() }),
+    second: z.object({ daemon: z.string(), agentId: z.string(), shortId: z.string(), name: z.string() }),
+    message: z.string().min(1).max(4000),
+  }),
+  output: z.object({
+    sends: z.array(
+      z.object({
+        daemon: z.string(),
+        agentId: z.string(),
+        ok: z.boolean(),
+        error: z.string().nullable(),
+      }),
+    ),
+  }),
+});
+
+export const daemonProbeRpc = defineRpc({
+  name: "daemon.probe",
+  input: z.object({ value: z.string().min(1).max(512) }),
+  output: z.object({
+    valid: z.boolean(),
+    formatError: z.string().nullable(),
+    reachable: z.boolean(),
+    error: z.string().nullable(),
+  }),
+});
+
+export const uiPrefsGetRpc = defineRpc({
+  name: "ui.prefs.get",
+  input: z.object({}),
+  output: z.object({
+    prereqsCollapsed: z.boolean(),
+    presenceEnabled: z.boolean(),
+    injectionEnabled: z.boolean(),
+    // Optional so a client still validates against a daemon that has not yet
+    // been reloaded with the outbox expiry field.
+    outboxExpirySeconds: z.number().int().positive().optional(),
+    daemonEnabled: z.record(z.string(), z.boolean()).optional(),
+  }),
+});
+
+export const uiPrefsSetRpc = defineRpc({
+  name: "ui.prefs.set",
+  input: z.object({
+    prereqsCollapsed: z.boolean(),
+    presenceEnabled: z.boolean().optional(),
+    injectionEnabled: z.boolean().optional(),
+    outboxExpirySeconds: z.number().int().positive().optional(),
+    daemonEnabled: z.record(z.string(), z.boolean()).optional(),
+  }),
+  output: z.object({
+    prereqsCollapsed: z.boolean(),
+    presenceEnabled: z.boolean(),
+    injectionEnabled: z.boolean(),
+    outboxExpirySeconds: z.number().int().positive().optional(),
+    daemonEnabled: z.record(z.string(), z.boolean()).optional(),
+  }),
+});
+
+export const snapshotRefreshRpc = defineRpc({
+  name: "snapshot.refresh",
+  input: z.object({}),
+  output: z.object({ updatedAt: z.string() }),
+});
+
+const PresenceBirthSchema = z.object({
+  serverId: z.string().min(1).max(128),
+  agentId: z.string().min(1).max(128),
+  name: z.string().max(256),
+  provider: z.string().max(128),
+  timestamp: z.string().min(1),
+});
+
+export const presenceAnnounceRpc = defineRpc({
+  name: "presence.announce",
+  input: z.object({
+    messageId: z.string().min(1).max(128),
+    entries: z.array(PresenceBirthSchema).max(500),
+  }),
+  output: z.object({
+    accepted: z.number(),
+    rejected: z.number(),
+  }),
+});
+
+export const presenceRetractRpc = defineRpc({
+  name: "presence.retract",
+  input: z.object({
+    messageId: z.string().min(1).max(128),
+    serverId: z.string().min(1).max(128),
+    agentId: z.string().min(1).max(128),
+    timestamp: z.string().min(1),
+  }),
+  output: z.object({ applied: z.boolean() }),
+});
+
+export const presenceListRpc = defineRpc({
+  name: "presence.list",
+  input: z.object({}),
+  output: z.object({
+    live: z.array(PresenceBirthSchema.extend({
+      origin: z.enum(["local", "remote"]),
+      lastSeenAt: z.string(),
+    })),
+    tombstones: z.array(z.object({
+      serverId: z.string(),
+      agentId: z.string(),
+      retractedAt: z.string(),
+    })),
+    pendingRetracts: z.number(),
+  }),
+});
+
+export const daemonDumpRpc = defineRpc({
+  name: "daemon.dump",
+  input: z.object({ daemon: z.string() }),
+  output: z.object({
+    name: z.string(),
+    reached: z.boolean(),
+    error: z.string().nullable(),
+    // Identity (handshake server_info)
+    serverId: z.string().nullable(),
+    hostname: z.string().nullable(),
+    version: z.string().nullable(),
+    desktopManaged: z.boolean().nullable(),
+    capabilities: z.record(z.string(), z.unknown()).nullable(),
+    features: z.record(z.string(), z.boolean()).nullable(),
+    // Connection / daemon status
+    listen: z.string().nullable(),
+    pid: z.number().nullable(),
+    nodePath: z.string().nullable(),
+    startedAt: z.string().nullable(),
+    relayEndpoints: z.array(z.string()).nullable(),
+    relayEnabled: z.boolean().nullable(),
+    transport: z.string().nullable(),
+    // Agents (full entries)
+    agents: z.array(
+      z.object({
+        agentId: z.string(), shortId: z.string(), name: z.string(), status: z.string(),
+        provider: z.string(), model: z.string().nullable(), providerOptions: z.record(z.string(), z.unknown()).nullable(),
+        cwd: z.string().nullable(), workspaceId: z.string().nullable(), projectName: z.string().nullable(),
+        createdAt: z.string().nullable(), archived: z.boolean().nullable(),
+      }),
+    ),
+    workspaces: z.array(z.object({ id: z.string(), name: z.string(), project: z.string(), isolation: z.string(), cwd: z.string().nullable() })),
+    projects: z.array(z.object({ id: z.string(), name: z.string(), source: z.string().nullable() })),
+    // Provider snapshot + recent sessions
+    providers: z.array(z.object({ provider: z.string(), available: z.boolean(), error: z.string().nullable() })),
+    providerCount: z.number(),
+    permissions: z.array(z.object({ id: z.string(), agentId: z.string(), name: z.string() })),
+    schedules: z.array(z.object({ id: z.string(), name: z.string(), state: z.string() })),
+    terminals: z.array(z.object({ id: z.string(), name: z.string(), cwd: z.string().nullable(), status: z.string().nullable() })),
+  }),
+});
+
+export const identitySyncRpc = defineRpc({
+  name: "identity.sync",
+  input: z.object({}),
+  output: z.object({
+    identities: z.record(z.string(), z.string()),
+    hostnames: z.record(z.string(), z.string()),
+  }),
+});
+
+export const conversationSendRpc = defineRpc({
+  name: "conversation.send",
+  input: z.object({
+    daemon: z.string(),
+    agentId: z.string(),
+    prompt: z.string(),
+    fromAgentId: z.string().nullable().optional(),
+    fromAgentName: z.string().nullable().optional(),
+  }),
+  output: z.object({
+    daemon: z.string(),
+    agentId: z.string(),
+    ok: z.boolean(),
+    error: z.string().nullable(),
+  }),
+});
+
+/**
+ * Consistency hint for direct hosts: if the value is a direct host (host:port
+ * or tcp://host:port) and the entered name does not match the URL host part,
+ * surface that as a warning. The name may legitimately differ from an IP, so
+ * this is advisory, not a rejection.
+ */
+export function directHostMismatch(name: string, value: string): string | null {
+  if (value.includes("#offer=") || value.startsWith("unix://") || value.startsWith("/")) {
+    return null;
+  }
+  const urlHost = value.replace(/^tcp:\/\//, "").replace(/^ws:\/\//, "").replace(/\?.*$/, "").split(":")[0];
+  if (!urlHost) return null;
+  const nameHost = name.split(":")[0];
+  if (nameHost && urlHost !== nameHost && !nameHost.includes(urlHost) && !urlHost.includes(nameHost)) {
+    return `host '${nameHost}' does not match the address host '${urlHost}'`;
+  }
+  return null;
+}

package/shared/vendor/paseo-plugin-helper/README.md

@@ -0,0 +1,11 @@
+# Vendored paseo-plugin-helper (Track B of issue #71, plugin #101)
+
+Pinned helper version: 0.4.0-beta.12
+
+Docs: https://github.com/xpufx/paseo/tree/main/packages/paseo-plugin-helper — npm: https://www.npmjs.com/package/paseo-plugin-helper
+
+Zero host requirements (no npm, no registry, no build key): the daemon bundles
+this source directly. Layout: `client/`, `server/`, `shared/` (+ `mcp/` under
+server) vendor splits mapping helper `src/` trees (daemon accepts modules only
+under those dirs). Updating: run `make vendor-sync` and bump the pinned version
+above.

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

@@ -0,0 +1,35 @@
+export class TimeoutError extends Error {
+  readonly timeoutMs: number;
+
+  constructor(message: string, timeoutMs: number) {
+    super(message);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/**
+ * Races a promise against a timeout duration in milliseconds.
+ * If the timeout expires before the promise resolves, rejects with a TimeoutError.
+ * Automatically cleans up the timer on resolution or rejection.
+ */
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  label = "Operation"
+): Promise<T> {
+  let timer: any;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new TimeoutError(`${label} timed out after ${timeoutMs}ms`, timeoutMs));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}

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

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import type { StatusVariant } from "./types";
+
+export const CustomPillThresholdsSchema = z.object({
+  warning: z.number().optional(),
+  danger: z.number().optional(),
+  /**
+   * If true, lower values trigger warnings/dangers instead of higher values
+   * (e.g. disk space remaining, battery percentage).
+   */
+  invert: z.boolean().optional(),
+});
+
+export const CustomPillModalSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  command: z.string().optional(),
+  /**
+   * Whether to format command output as monospace preformatted text (default: true).
+   */
+  preformatted: z.boolean().default(true),
+});
+
+export const CustomPillDefinitionSchema = z.object({
+  /**
+   * Unique identifier for the custom pill (e.g. "gpu-util", "docker-count").
+   */
+  id: z.string().min(1),
+
+  /**
+   * Title shown in the composer trackbar (e.g. "GPU", "Docker").
+   */
+  title: z.string().min(1),
+
+  /**
+   * Compact title shown when layout is compact (e.g. "G"). Defaults to title.
+   */
+  compactTitle: z.string().optional(),
+
+  /**
+   * Lucide icon name (e.g. "Cpu", "Flame", "HardDrive", "Layers").
+   */
+  icon: z.string().optional(),
+
+  /**
+   * Optional compact icon name. Defaults to icon.
+   */
+  compactIcon: z.string().optional(),
+
+  /**
+   * Shell command executed periodically to produce the pill's value.
+   * Can use session environment variables like $PASEO_AGENT_ID, $PASEO_WORKSPACE_ID.
+   */
+  command: z.string().min(1),
+
+  /**
+   * Optional prefix prepended to the output value (e.g. "$", "#").
+   */
+  prefix: z.string().optional(),
+
+  /**
+   * Optional suffix appended to the output value (e.g. "%", "ms", "GB").
+   */
+  suffix: z.string().optional(),
+
+  /**
+   * Polling interval in milliseconds. Minimum 500ms, defaults to 5000ms.
+   */
+  intervalMs: z.number().min(500).default(5000),
+
+  /**
+   * Execution timeout in milliseconds. Defaults to 10000ms.
+   */
+  timeoutMs: z.number().min(500).default(10000),
+
+  /**
+   * Optional threshold rules to automatically transition badge color to warning or danger.
+   */
+  thresholds: CustomPillThresholdsSchema.optional(),
+
+  /**
+   * Optional modal configuration shown when the pill is pressed.
+   */
+  modal: CustomPillModalSchema.optional(),
+
+  /**
+   * Whether this custom pill is enabled. Defaults to true.
+   */
+  enabled: z.boolean().default(true),
+
+  /**
+   * Absolute path to the config file that defined this pill (e.g.
+   * ~/.paseo/top/pills/disk-usage.jsonc). Injected at discovery time; not
+   * intended to be authored in the config file itself.
+   */
+  sourceFile: z.string().optional(),
+});
+
+export type CustomPillDefinition = z.infer<typeof CustomPillDefinitionSchema>;
+export type CustomPillThresholds = z.infer<typeof CustomPillThresholdsSchema>;
+export type CustomPillModal = z.infer<typeof CustomPillModalSchema>;
+
+export interface CustomPillState {
+  id: string;
+  title: string;
+  compactTitle?: string;
+  icon?: string;
+  compactIcon?: string;
+  rawValue: string;
+  displayValue: string;
+  numericValue?: number;
+  status: StatusVariant;
+  lastUpdated: number;
+  error?: string;
+  sourceFile?: string;
+  modalTitle?: string;
+  modalDescription?: string;
+  modalOutput?: string;
+  modalError?: string;
+  modalLastUpdated?: number;
+}
+
+/**
+ * Extracts a numeric value from the raw command output string (e.g. "45.2%" -> 45.2).
+ */
+export function parseNumericPillValue(rawValue: string): number | undefined {
+  const match = rawValue.match(/-?\d+(\.\d+)?/);
+  if (!match) return undefined;
+  const num = parseFloat(match[0]);
+  return Number.isNaN(num) ? undefined : num;
+}
+
+/**
+ * Resolves the status variant based on numeric value and thresholds.
+ */
+export function resolveCustomPillStatus(
+  numericValue: number | undefined,
+  thresholds?: CustomPillThresholds,
+): StatusVariant {
+  if (numericValue === undefined || !thresholds) {
+    return "neutral";
+  }
+
+  const { warning, danger, invert } = thresholds;
+
+  if (invert) {
+    if (danger !== undefined && numericValue <= danger) return "danger";
+    if (warning !== undefined && numericValue <= warning) return "warning";
+    return "success";
+  }
+
+  if (danger !== undefined && numericValue >= danger) return "danger";
+  if (warning !== undefined && numericValue >= warning) return "warning";
+  return "neutral";
+}
+
+/**
+ * Formats the raw output string with optional prefix and suffix.
+ */
+export function formatPillDisplay(
+  rawValue: string,
+  prefix?: string,
+  suffix?: string,
+): string {
+  const cleaned = rawValue.trim();
+  const pre = prefix ?? "";
+  const suf = suffix ?? "";
+  return `${pre}${cleaned}${suf}`;
+}

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

@@ -0,0 +1,110 @@
+/**
+ * Shared forge brand-mark resolution.
+ *
+ * One host/kind -> mark table for every plugin that shows forge iconography,
+ * so plugins never carry their own per-forge icon maps. The client-side
+ * `<ForgeIcon>` renders this descriptor; server/shared code can consume the
+ * pure resolver without pulling in React.
+ *
+ * GitHub and GitLab resolve to their Lucide marks; Codeberg, Forgejo and Gitea
+ * have no Lucide equivalent and resolve to helper-drawn official mono marks.
+ */
+
+export type ForgeKind =
+  | "github"
+  | "gitlab"
+  | "codeberg"
+  | "forgejo"
+  | "gitea"
+  | "generic";
+
+export interface ResolvedForgeMark {
+  /** Stable forge identity. */
+  kind: ForgeKind;
+  /** Human-readable forge name for labels and accessibility. */
+  label: string;
+  /** Host Lucide icon name; the exact mark on hosts with SVG support, the closest fallback otherwise. */
+  lucideName: string;
+  /** True when `<ForgeIcon>` draws the official mark instead of delegating to the host icon set. */
+  custom: boolean;
+}
+
+export interface ForgeMarkInput {
+  /** Forge hostname, e.g. `codeberg.org` or `forge.example.com`. */
+  host?: string | null;
+  /** Explicit forge identity; wins over host detection when it names a known forge. */
+  kind?: ForgeKind | string | null;
+}
+
+const FORGE_MARKS: Record<ForgeKind, ResolvedForgeMark> = {
+  github: { kind: "github", label: "GitHub", lucideName: "Github", custom: false },
+  gitlab: { kind: "gitlab", label: "GitLab", lucideName: "Gitlab", custom: false },
+  codeberg: { kind: "codeberg", label: "Codeberg", lucideName: "Mountain", custom: true },
+  forgejo: { kind: "forgejo", label: "Forgejo", lucideName: "Hammer", custom: true },
+  gitea: { kind: "gitea", label: "Gitea", lucideName: "Coffee", custom: true },
+  generic: { kind: "generic", label: "Git forge", lucideName: "Globe", custom: false },
+};
+
+const FORGE_KINDS: ForgeKind[] = [
+  "github",
+  "gitlab",
+  "codeberg",
+  "forgejo",
+  "gitea",
+  "generic",
+];
+
+/**
+ * Reduce a remote URL, `owner/repo` slug or bare hostname to a lowercase
+ * hostname without scheme, userinfo, port, path or a leading `www.`.
+ */
+export function normalizeForgeHost(host: string | null | undefined): string | null {
+  if (!host || typeof host !== "string") return null;
+  let value = host.trim().toLowerCase();
+  if (!value) return null;
+  value = value.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+  value = value.replace(/^[^@/]+@/, "");
+  value = value.split("/")[0]!.split("?")[0]!.split("#")[0]!;
+  // Cuts both `host:port` and SCP-style `host:owner/repo` tails.
+  value = value.split(":")[0]!;
+  value = value.replace(/^www\./, "").replace(/\.$/, "");
+  return value || null;
+}
+
+// Ordered: the first match wins. Self-hosted instances routinely carry the
+// project name in their hostname (e.g. `forgejo.example.com`); everything else
+// is an unknown forge and gets the generic fallback.
+const HOST_KIND_RULES: Array<{ matches: (host: string) => boolean; kind: ForgeKind }> = [
+  { matches: (h) => h === "github.com" || h.endsWith(".github.com"), kind: "github" },
+  { matches: (h) => h === "gitlab.com" || h.endsWith(".gitlab.com"), kind: "gitlab" },
+  { matches: (h) => h === "codeberg.org" || h.endsWith(".codeberg.org"), kind: "codeberg" },
+  { matches: (h) => h === "forgejo.org" || h.endsWith(".forgejo.org") || h.includes("forgejo"), kind: "forgejo" },
+  { matches: (h) => h === "gitea.com" || h === "gitea.io" || h.includes("gitea"), kind: "gitea" },
+];
+
+export function isForgeKind(value: unknown): value is ForgeKind {
+  return typeof value === "string" && FORGE_KINDS.includes(value as ForgeKind);
+}
+
+export function forgeKindFromHost(host: string | null | undefined): ForgeKind {
+  const normalized = normalizeForgeHost(host);
+  if (!normalized) return "generic";
+  for (const rule of HOST_KIND_RULES) {
+    if (rule.matches(normalized)) return rule.kind;
+  }
+  return "generic";
+}
+
+/**
+ * Resolve a forge descriptor from a hostname and/or explicit kind. Accepts a
+ * bare host string for the common host-only case.
+ */
+export function resolveForgeMark(
+  input: ForgeMarkInput | string | null | undefined,
+): ResolvedForgeMark {
+  const { host, kind } =
+    input !== null && typeof input === "object" ? input : { host: input, kind: null };
+  const explicit = typeof kind === "string" ? kind.trim().toLowerCase() : null;
+  const resolved = isForgeKind(explicit) ? explicit : forgeKindFromHost(host);
+  return FORGE_MARKS[resolved];
+}