@xpufx/paseo-x-comms 0.3.0

package/server/registry.ts

@@ -0,0 +1,215 @@
+import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync } from "node:fs";
+export { directHostMismatch } from "../shared/registry.ts";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+// All plugin state lives under a single namespaced subdir of paseo's home
+// (~/.paseo/paseo-x-comms/) rather than littering ~/.paseo root.
+export function stateDir(): string {
+  return join(homedir(), ".paseo", "paseo-x-comms");
+}
+
+export const REGISTRY_DEFAULT = join(stateDir(), "registry.json");
+
+// One-time migration: move a file from the old ~/.paseo root location into the
+// namespaced state dir. Deterministic and forward-only; never a fallback path.
+export function migrateFromRoot(oldName: string, newPath: string): void {
+  const oldPath = join(homedir(), ".paseo", oldName);
+  if (!existsSync(oldPath) || existsSync(newPath)) return;
+  mkdirSync(stateDir(), { recursive: true });
+  renameSync(oldPath, newPath);
+}
+
+/** The plausible canonical forms paseo classifies as --host targets. */
+export function validateDaemonHost(value: string): { valid: boolean; error: string | null } {
+  const v = value.trim();
+  if (v.length === 0) return { valid: false, error: "empty value" };
+
+  // Relay offer: any value containing #offer= (E2EE via relay).
+  if (v.includes("#offer=")) {
+    if (/^https?:\/\//.test(v)) return { valid: true, error: null };
+    return { valid: false, error: "#offer= value must be a full pairing URL (https://…)" };
+  }
+
+  // tcp://host:port with optional query (ssl, password).
+  if (v.startsWith("tcp://")) {
+    if (/^tcp:\/\/[^/]+\/\?.*$|^tcp:\/\/[^/]+$/.test(v)) return { valid: true, error: null };
+    return { valid: false, error: "tcp:// must include host[:port] (tcp://host:port?ssl=true…) " };
+  }
+
+  // unix:///path or pipe://…
+  if (v.startsWith("unix://") || v.startsWith("pipe://")) {
+    if (v.length > 7) return { valid: true, error: null };
+    return { valid: false, error: "missing path after scheme" };
+  }
+
+  // absolute paths
+  if (v.startsWith("/")) return { valid: true, error: null };
+
+  // bare port → 127.0.0.1:port
+  if (/^\d+$/.test(v)) return { valid: true, error: null };
+
+  // host:port, IPv6 [::1]:6767
+  if (/^\[[0-9a-fA-F:.]+\]:\d+$/.test(v)) return { valid: true, error: null };
+  if (/^[^/:]+:\d+$/.test(v)) return { valid: true, error: null };
+
+  return { valid: false, error: "not a canonical form (relay URL, host:port, tcp://, unix://, bare port)" };
+}
+
+export function parseRegistry(content: string): {
+  ok: boolean;
+  daemons: Array<{ name: string; value: string; valid: boolean; error: string | null }>;
+  parseError: string | null;
+} {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch (cause) {
+    return {
+      ok: false,
+      daemons: [],
+      parseError: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, daemons: [], parseError: "registry must be a JSON object of name → host" };
+  }
+  const daemons = Object.entries(parsed as Record<string, unknown>).map(([name, value]) => {
+    if (typeof value !== "string") {
+      return { name, value: String(value), valid: false, error: "value must be a string" };
+    }
+    const checked = validateDaemonHost(value);
+    return { name, value, ...checked };
+  });
+  return { ok: true, daemons, parseError: null };
+}
+
+export function currentRegistryPath(): string {
+  const env = process.env.PASEO_X_COMMS_REMOTES;
+  if (env && env.length > 0) return env;
+  return REGISTRY_DEFAULT;
+}
+
+export function validateDaemonName(name: string): { valid: boolean; error: string | null } {
+  const n = name.trim();
+  if (n.length === 0) return { valid: false, error: "name is required" };
+  if (!/^[A-Za-z0-9._-]+$/.test(n)) {
+    return { valid: false, error: "name may only contain letters, digits, '.', '_', '-'" };
+  }
+  return { valid: true, error: null };
+}
+
+/** Reads + validates the registry file, returning the entry list only. */
+export function readRegistry(
+  path: string,
+): { ok: boolean; exists: boolean; parseError: string | null; daemons: Array<{ name: string; value: string; valid: boolean; error: string | null }> } {
+  if (!existsSync(path)) {
+    return { ok: true, exists: false, parseError: null, daemons: [] };
+  }
+  const content = readFileSync(path, "utf8");
+  const parsed = parseRegistry(content);
+  return { ok: parsed.ok, exists: true, parseError: parsed.parseError, daemons: parsed.daemons };
+}
+
+/**
+ * Applies a mutation to the registry and writes it only when every entry is
+ * valid. Returns fresh state plus whether the write happened; on any invalid
+ * entry the file is left untouched.
+ */
+export function mutateRegistry(
+  path: string,
+  mutate: (daemons: Record<string, string>) => Record<string, string>,
+): {
+  saved: boolean;
+  error: string | null;
+  registryPath: string;
+  daemons: Array<{ name: string; value: string; valid: boolean; error: string | null }>;
+} {
+  const current = readRegistry(path);
+  if (!current.ok) {
+    return {
+      saved: false,
+      error: `existing registry is not valid JSON: ${current.parseError}`,
+      registryPath: path,
+      daemons: [],
+    };
+  }
+  const existing: Record<string, string> = {};
+  for (const daemon of current.daemons) existing[daemon.name] = daemon.value;
+
+  let next: Record<string, string>;
+  try {
+    next = mutate(existing);
+  } catch (cause) {
+    return {
+      saved: false,
+      error: cause instanceof Error ? cause.message : String(cause),
+      registryPath: path,
+      daemons: current.daemons,
+    };
+  }
+
+  const entries = Object.entries(next).map(([name, value]) => ({ name, value, ...validateDaemonHost(value) }));
+  const invalid = entries.find((entry) => !entry.valid);
+  if (invalid) {
+    return {
+      saved: false,
+      error: `${invalid.name} is not a valid daemon host: ${invalid.error}`,
+      registryPath: path,
+      daemons: entries,
+    };
+  }
+  // Two names must not point at the same host; that is almost always a copy
+  // bug, not an intentional alias.
+  const seen = new Map<string, string>();
+  for (const entry of entries) {
+    const prior = seen.get(entry.value);
+    if (prior !== undefined) {
+      return {
+        saved: false,
+        error: `${entry.name} and ${prior} use the same host value`,
+        registryPath: path,
+        daemons: entries,
+      };
+    }
+    seen.set(entry.value, entry.name);
+  }
+  if (JSON.stringify(sortEntries(current.daemons)) === JSON.stringify(sortEntries(entries))) {
+    // No change; still report success so the UI can settle.
+    return { saved: true, error: null, registryPath: path, daemons: entries };
+  }
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return { saved: true, error: null, registryPath: path, daemons: entries };
+  } catch (cause) {
+    return {
+      saved: false,
+      error: cause instanceof Error ? cause.message : String(cause),
+      registryPath: path,
+      daemons: entries,
+    };
+  }
+}
+
+function sortEntries(daemons: Array<{ name: string; value: string }>): Array<{ name: string; value: string }> {
+  return [...daemons].sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Derives the canonical host for a registry value, when it can be done
+ * deterministically. Relay offers embed their serverId, so the real host is
+ * that id. Direct/local hosts carry no identity, so nothing is derived and the
+ * user must supply the name themselves.
+ */
+export function deriveHostFromValue(value: string): string | null {
+  const offer = value.match(/#offer=([A-Za-z0-9_-]+)/);
+  if (offer) {
+    try {
+      const payload = JSON.parse(Buffer.from(offer[1], "base64").toString("utf8"));
+      return typeof payload.serverId === "string" ? payload.serverId : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

package/server/relay-status.ts

@@ -0,0 +1,9 @@
+// `paseo daemon status --json` reports `relay` as a string: the literal
+// "disabled" when no relay is configured, otherwise the public relay URL
+// (e.g. "wss://relay.paseo.sh:443").
+export function readRelayStatus(raw: unknown): { enabled: boolean | null; endpoints: string[] | null } {
+  if (typeof raw !== "string") return { enabled: null, endpoints: null };
+  const endpoint = raw.trim();
+  if (endpoint === "" || endpoint === "disabled") return { enabled: false, endpoints: null };
+  return { enabled: true, endpoints: [endpoint] };
+}

package/server/server-status.ts

@@ -0,0 +1,138 @@
+import { fileURLToPath } from "node:url";
+import { dirname, isAbsolute, join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+
+const BUNDLED = "paseo-x-comms.bundled.mjs";
+const PLAIN = "paseo-x-comms.mjs";
+
+/** Bundled first: it is the self-contained artifact the injector copies. */
+function inMcpDir(base: string): string[] {
+  return [join(base, "mcp", BUNDLED), join(base, "mcp", PLAIN)];
+}
+
+/**
+ * Explicit override. Set `PASEO_X_COMMS_MCP_SERVER` when the host layout is
+ * unusual (packaged app, moved checkout, a build that vendors the plugin).
+ */
+function overrideCandidates(): string[] {
+  const raw = process.env.PASEO_X_COMMS_MCP_SERVER?.trim();
+  return raw ? [isAbsolute(raw) ? raw : join(process.cwd(), raw)] : [];
+}
+
+/** Plugin ids this plugin may be installed under. */
+const SELF_PLUGIN_IDS = ["x-comms", "paseo-x-comms", "paseo-x-comms-plugin"];
+
+/**
+ * Directories the daemon records for installed plugins, with this plugin's own
+ * entries first so a sibling install can never shadow it.
+ */
+function configCandidates(selfDir?: string): string[] {
+  const configPath = join(homedir(), ".paseo", "config.json");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch {
+    return [];
+  }
+  const plugins = (parsed as { plugins?: unknown })?.plugins;
+  if (!plugins || typeof plugins !== "object") return [];
+
+  const preferred: string[] = [];
+  const rest: string[] = [];
+  for (const [id, entry] of Object.entries(plugins as Record<string, unknown>)) {
+    const dir = (entry as { path?: unknown })?.path;
+    if (typeof dir !== "string" || !dir.trim()) continue;
+    const isSelf = SELF_PLUGIN_IDS.includes(id) || (selfDir !== undefined && dir === selfDir);
+    (isSelf ? preferred : rest).push(dir);
+  }
+  return [...preferred, ...rest].flatMap(inMcpDir);
+}
+
+/**
+ * Managed-install layout:
+ * `~/.paseo/plugins/<pluginId>/<commit>/checkout/mcp/...`.
+ */
+function managedCandidates(): string[] {
+  const out: string[] = [];
+  for (const pluginId of SELF_PLUGIN_IDS) {
+    const base = join(homedir(), ".paseo", "plugins", pluginId);
+    if (!existsSync(base)) continue;
+    let entries;
+    try {
+      entries = readdirSync(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      out.push(...inMcpDir(join(base, entry.name, "checkout")));
+    }
+  }
+  return out;
+}
+
+/**
+ * `import.meta.url` works only when the server is executed unbundled. Paseo
+ * bundles and inlines plugin server code, so this is usually empty — kept for
+ * tests, `tsx`, and any executor that runs the sources directly.
+ */
+function moduleCandidates(): string[] {
+  try {
+    const url = (import.meta as unknown as { url?: string })?.url;
+    if (!url) return [];
+    const here = dirname(fileURLToPath(url));
+    return [...inMcpDir(here), ...inMcpDir(join(here, ".."))];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Working-directory candidates.
+ *
+ * Paseo does **not** spawn plugin subprocesses from the plugin directory (the
+ * daemon inherits its own cwd), so this is a low-priority fallback that helps
+ * when a plugin is run directly (tests, tsx).
+ */
+function cwdCandidates(): string[] {
+  const cwd = process.cwd();
+  return [...inMcpDir(cwd), ...inMcpDir(join(cwd, ".."))];
+}
+
+/**
+ * Ordered candidate paths for the bundled MCP server, highest-confidence first.
+ *
+ * Exported for tests and diagnostics.
+ *
+ * @param selfDir directory the daemon recorded for THIS plugin, when known.
+ */
+export function serverCandidates(selfDir?: string): string[] {
+  return [
+    ...overrideCandidates(),
+    ...configCandidates(selfDir),
+    ...managedCandidates(),
+    ...moduleCandidates(),
+    ...cwdCandidates(),
+  ];
+}
+
+/**
+ * Absolute path of the bundled x-comms MCP server.
+ *
+ * A plugin server is bundled and inlined before it runs, so neither
+ * `import.meta.url` nor `process.cwd()` identifies the plugin checkout
+ * (xpufx-org/paseo#214). The dependable locator is the install path the daemon
+ * records in `~/.paseo/config.json`, with an explicit env override on top and
+ * the managed-checkout / module / cwd layouts as fallbacks.
+ *
+ * @param selfDir directory the daemon recorded for this plugin, when known.
+ */
+export function serverPath(selfDir?: string): string {
+  for (const candidate of serverCandidates(selfDir)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(
+    "could not locate bundled mcp server (mcp/paseo-x-comms.mjs); set PASEO_X_COMMS_MCP_SERVER to the bundled .mjs path",
+  );
+}

package/server/settings.ts

@@ -0,0 +1,81 @@
+/**
+ * Daemon-wide feature flags for the mesh layers. Pure resolution logic lives
+ * here so it is unit-testable without touching the prefs file; persistence
+ * stays in server/handlers.ts via the PluginStorage-backed ui prefs.
+ *
+ * Defaults: presence on, injection on. Absent keys mean enabled.
+ */
+
+export interface FeaturePrefs {
+  presenceEnabled?: boolean;
+  injectionEnabled?: boolean;
+  /** How long an undelivered outbox message is retried before it expires. */
+  outboxExpirySeconds?: number;
+  /** Per-daemon enablement; an absent or non-false entry means enabled. */
+  daemonEnabled?: Record<string, boolean>;
+}
+
+export const OUTBOX_EXPIRY_DEFAULT_SECONDS = 10 * 60;
+export const OUTBOX_EXPIRY_MIN_SECONDS = 10;
+export const OUTBOX_EXPIRY_MAX_SECONDS = 24 * 60 * 60;
+
+/**
+ * Outbox expiry in ms. Absent/invalid values fall back to the 10 minute
+ * default; explicit values are clamped to a sane range so a bad setting cannot
+ * disable retries or hold messages forever.
+ */
+export function resolveOutboxExpiryMs(prefs: FeaturePrefs): number {
+  const raw = prefs.outboxExpirySeconds;
+  const seconds =
+    typeof raw === "number" && Number.isFinite(raw)
+      ? Math.floor(raw)
+      : OUTBOX_EXPIRY_DEFAULT_SECONDS;
+  const clamped = Math.min(OUTBOX_EXPIRY_MAX_SECONDS, Math.max(OUTBOX_EXPIRY_MIN_SECONDS, seconds));
+  return clamped * 1000;
+}
+
+export function resolvePresenceEnabled(prefs: FeaturePrefs): boolean {
+  return prefs.presenceEnabled !== false;
+}
+
+export function resolveDaemonEnabled(prefs: FeaturePrefs, name: string): boolean {
+  return prefs.daemonEnabled?.[name] !== false;
+}
+
+export function resolveInjectionEnabled(prefs: FeaturePrefs): boolean {
+  return prefs.injectionEnabled !== false;
+}
+
+export interface FeatureFlags {
+  presenceEnabled: boolean;
+  injectionEnabled: boolean;
+}
+
+export function resolveFeatureFlags(prefs: FeaturePrefs): FeatureFlags {
+  return {
+    presenceEnabled: resolvePresenceEnabled(prefs),
+    injectionEnabled: resolveInjectionEnabled(prefs),
+  };
+}
+
+/**
+ * Merge a partial prefs update over stored prefs (toggle round-trip).
+ * Undefined fields keep their stored value.
+ */
+export function applyFeaturePrefsUpdate(
+  stored: FeaturePrefs,
+  input: FeaturePrefs,
+): FeaturePrefs {
+  const daemonEnabled = input.daemonEnabled
+    ? { ...stored.daemonEnabled, ...input.daemonEnabled }
+    : stored.daemonEnabled;
+  return {
+    ...stored,
+    presenceEnabled: input.presenceEnabled ?? stored.presenceEnabled,
+    injectionEnabled: input.injectionEnabled ?? stored.injectionEnabled,
+    ...(input.outboxExpirySeconds !== undefined
+      ? { outboxExpirySeconds: input.outboxExpirySeconds }
+      : {}),
+    ...(daemonEnabled !== undefined ? { daemonEnabled } : {}),
+  };
+}

package/server/snapshot.ts

@@ -0,0 +1,176 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createPluginLogger, safeSpawn } from "paseo-plugin-helper/server";
+import { currentRegistryPath, readRegistry, stateDir, migrateFromRoot } from "./registry";
+
+const snapLog = createPluginLogger("paseo-x-comms", { subsystem: "snapshot" });
+
+const PROBE_TIMEOUT_MS = 15000;
+const SNAPSHOT_FILE = join(stateDir(), "snapshot.json");
+migrateFromRoot("paseo-x-comms-snapshot.json", SNAPSHOT_FILE);
+const STALE_MS = 60_000;
+
+export interface SnapshotAgent {
+  agentId: string;
+  shortId: string;
+  name: string;
+  status: string;
+}
+
+export interface SnapshotWorkspace {
+  name: string;
+  agents: SnapshotAgent[];
+}
+
+export interface SnapshotProject {
+  project: string;
+  workspaces: SnapshotWorkspace[];
+}
+
+export interface DaemonSnapshotEntry {
+  name: string;
+  value: string;
+  reachable: boolean;
+  error: string | null;
+  projects: SnapshotProject[];
+}
+
+export interface DaemonSnapshot {
+  updatedAt: string;
+  daemons: DaemonSnapshotEntry[];
+}
+
+let snapshot: DaemonSnapshot | null = null;
+let inflight: Promise<DaemonSnapshot> | null = null;
+
+async function runPaseoJson(args: string[]): Promise<unknown> {
+  const r = await safeSpawn("paseo", args, { timeoutMs: PROBE_TIMEOUT_MS });
+  if (r.code !== 0) throw new Error((r.stderr || `exit ${r.code}`).trim());
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    throw new Error("paseo returned non-JSON output");
+  }
+}
+
+async function probeDaemon(value: string): Promise<{
+  reachable: boolean;
+  error: string | null;
+  projects: SnapshotProject[];
+}> {
+  try {
+    const [agentsRaw, workspacesRaw] = await Promise.all([
+      // --global: include agents in every workspace, not just the daemon cwd.
+      runPaseoJson(["ls", "--global", "--host", value, "--json"]),
+      runPaseoJson(["workspace", "ls", "--host", value, "--json"]),
+    ]);
+    const agents = Array.isArray(agentsRaw) ? agentsRaw : [];
+    const workspaces = Array.isArray(workspacesRaw) ? workspacesRaw : [];
+
+    // Map cwd -> { project, name } for grouping agents under their workspace.
+    const infoByCwd = new Map<string, { project: string; name: string }>();
+    for (const ws of workspaces) {
+      if (typeof ws?.cwd === "string" && typeof ws?.name === "string") {
+        infoByCwd.set(ws.cwd, {
+          project: typeof ws.project === "string" && ws.project ? ws.project : "(no project)",
+          name: ws.name,
+        });
+      }
+    }
+
+    const agentsByCwd = new Map<string, SnapshotAgent[]>();
+    for (const agent of agents) {
+      // Skip non-active agents; the registry's view is of current agents.
+      const status = typeof agent.status === "string" ? agent.status : "unknown";
+      if (status === "closed" || status === "archived") continue;
+      const id = typeof agent.id === "string" ? agent.id : String(agent.id ?? "");
+      const key = typeof agent.cwd === "string" ? agent.cwd : "";
+      if (!agentsByCwd.has(key)) agentsByCwd.set(key, []);
+      agentsByCwd.get(key)!.push({
+        agentId: id,
+        shortId: typeof agent.shortId === "string" ? agent.shortId : id.slice(0, 8),
+        name: typeof agent.name === "string" ? agent.name : id,
+        status,
+      });
+    }
+
+    const byProject = new Map<string, Map<string, SnapshotAgent[]>>();
+    for (const [cwd, list] of agentsByCwd) {
+      // Agents whose cwd matches no listed workspace are grouped under their
+      // actual working directory, so the label stays truthful.
+      const info = infoByCwd.get(cwd) ?? { project: "(no workspace)", name: cwd };
+      if (!byProject.has(info.project)) byProject.set(info.project, new Map());
+      const byWorkspace = byProject.get(info.project)!;
+      if (!byWorkspace.has(info.name)) byWorkspace.set(info.name, []);
+      byWorkspace.get(info.name)!.push(...list);
+    }
+
+    const projects: SnapshotProject[] = [];
+    for (const [project, byWorkspace] of byProject) {
+      const workspacesOut: SnapshotWorkspace[] = [];
+      for (const [name, list] of byWorkspace) {
+        workspacesOut.push({ name, agents: list.sort((a, b) => a.name.localeCompare(b.name)) });
+      }
+      projects.push({ project, workspaces: workspacesOut.sort((a, b) => a.name.localeCompare(b.name)) });
+    }
+    projects.sort((a, b) => a.project.localeCompare(b.project));
+    return { reachable: true, error: null, projects };
+  } catch (cause) {
+    return { reachable: false, error: cause instanceof Error ? cause.message : String(cause), projects: [] };
+  }
+}
+
+function doRefresh(): Promise<DaemonSnapshot> {
+  return (async () => {
+    const current = readRegistry(currentRegistryPath());
+    const daemons: DaemonSnapshotEntry[] = current.ok
+      ? await Promise.all(
+          current.daemons.map(async (daemon) => ({
+            name: daemon.name,
+            value: daemon.value,
+            ...(await probeDaemon(daemon.value)),
+          })),
+        )
+      : [];
+    const next: DaemonSnapshot = { updatedAt: new Date().toISOString(), daemons };
+    snapshot = next;
+    try {
+      writeFileSync(SNAPSHOT_FILE, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 });
+    } catch {
+      // The in-memory snapshot is authoritative; a failed state file write is not fatal.
+    }
+    return next;
+  })();
+}
+
+/** Re-probe every registered daemon and replace the snapshot. */
+export function refreshSnapshot(): Promise<DaemonSnapshot> {
+  if (!inflight) {
+    inflight = doRefresh().finally(() => {
+      inflight = null;
+    });
+  }
+  return inflight;
+}
+
+/** Returns the current snapshot, refreshing only if it is stale. */
+export function getSnapshotFresh(): Promise<DaemonSnapshot> {
+  if (snapshot && Date.now() - new Date(snapshot.updatedAt).getTime() < STALE_MS) {
+    return Promise.resolve(snapshot);
+  }
+  return refreshSnapshot();
+}
+
+/** Kick off a first snapshot at plugin load; never throws at startup. */
+export function initializeSnapshot(): void {
+  void refreshSnapshot().catch((error) => {
+    snapLog.error(`initial refresh failed: ${error instanceof Error ? error.message : error}`);
+  });
+}
+
+export function agentCountFor(entry: DaemonSnapshotEntry): number {
+  return entry.projects.reduce(
+    (total, project) => total + project.workspaces.reduce((sub, ws) => sub + ws.agents.length, 0),
+    0,
+  );
+}