@xpufx/paseo-x-comms 0.3.0

package/server/peer-channel.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { buildDaemonWebSocketUrl, buildRelayWebSocketUrl } from "@getpaseo/protocol/daemon-endpoints";
+import { createPluginLogger, safeSpawn } from "paseo-plugin-helper/server";
+import { withTimeout } from "paseo-plugin-helper/shared";
+
+const log = createPluginLogger("paseo-x-comms", { subsystem: "peer-channel" });
+const CONNECT_TIMEOUT_MS = 8000;
+
+export interface PeerTarget {
+  name: string;
+  endpoint: string;
+  url: string;
+  e2eePublicKeyB64: string | null;
+  expectedServerId: string | null;
+}
+
+interface ParsedOffer {
+  serverId: string | null;
+  daemonPublicKeyB64: string | null;
+  relayEndpoint: string | null;
+  useTls: boolean;
+}
+
+function parseOffer(value: string): ParsedOffer | null {
+  const m = value.match(/#offer=([A-Za-z0-9_-]+)/);
+  if (!m) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(m[1], "base64").toString("utf8"));
+    return {
+      serverId: typeof payload.serverId === "string" ? payload.serverId : null,
+      daemonPublicKeyB64: typeof payload.daemonPublicKeyB64 === "string" ? payload.daemonPublicKeyB64 : null,
+      relayEndpoint: typeof payload.relay?.endpoint === "string" ? payload.relay.endpoint : null,
+      useTls: payload.relay?.useTls === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a registry endpoint to a dialable peer target. Relay offers carry
+ * everything needed (relay URL, daemon key, expected serverId). Direct
+ * host:port targets carry no identity: expectedServerId stays null and the
+ * link check falls back to whatever the handshake reports.
+ */
+export function resolvePeerTarget(name: string, endpoint: string): PeerTarget {
+  const value = endpoint.trim();
+  const offer = parseOffer(value);
+  if (offer) {
+    if (!offer.relayEndpoint || !offer.daemonPublicKeyB64 || !offer.serverId) {
+      throw new Error(`relay offer for '${name}' is missing endpoint, key, or serverId`);
+    }
+    return {
+      name,
+      endpoint: value,
+      url: buildRelayWebSocketUrl({
+        endpoint: offer.relayEndpoint,
+        useTls: offer.useTls,
+        serverId: offer.serverId,
+        role: "client",
+      }),
+      e2eePublicKeyB64: offer.daemonPublicKeyB64,
+      expectedServerId: offer.serverId,
+    };
+  }
+  const direct = value.replace(/^tcp:\/\//, "").split("?")[0];
+  if (/^[^/:]+:\d+$/.test(direct) || /^\[[0-9a-fA-F:.]+\]:\d+$/.test(direct)) {
+    return {
+      name,
+      endpoint: value,
+      url: buildDaemonWebSocketUrl(direct, { useTls: false }),
+      e2eePublicKeyB64: null,
+      expectedServerId: null,
+    };
+  }
+  throw new Error(`cannot dial '${name}': unsupported endpoint form for presence RPC`);
+}
+
+let cachedLocalServerId: string | null = null;
+
+/**
+ * This daemon's own serverId. Read from the daemon-persisted server-id file,
+ * falling back to a local status probe. Never from agent config or payloads.
+ */
+export async function localServerId(): Promise<string> {
+  if (cachedLocalServerId) return cachedLocalServerId;
+  try {
+    const id = readFileSync(join(homedir(), ".paseo", "server-id"), "utf8").trim();
+    if (id) {
+      cachedLocalServerId = id;
+      return id;
+    }
+  } catch {
+    // Fall through to the status probe.
+  }
+  const r = await withTimeout(
+    safeSpawn("paseo", ["daemon", "status", "--json"], { timeoutMs: 8000 }),
+    8000,
+    "local daemon status",
+  );
+  if (r.code !== 0) throw new Error(`local daemon status failed: ${(r.stderr || `exit ${r.code}`).trim()}`);
+  const parsed = JSON.parse(r.stdout) as { serverId?: unknown };
+  if (typeof parsed.serverId !== "string" || !parsed.serverId) {
+    throw new Error("local daemon status reports no serverId");
+  }
+  cachedLocalServerId = parsed.serverId;
+  return parsed.serverId;
+}
+
+/**
+ * Invoke a plugin RPC on a peer over its authenticated channel and return the
+ * link-verified serverId of the far end. The handshake identity is checked
+ * against the expected id when the endpoint carries one (relay offers do);
+ * a mismatch aborts before any payload is sent.
+ */
+export async function invokePeerRpc(
+  target: PeerTarget,
+  method: string,
+  input: unknown,
+): Promise<{ peerServerId: string | null }> {
+  const client = new DaemonClient({
+    url: target.url,
+    clientId: randomUUID(),
+    clientType: "cli",
+    appVersion: "paseo-x-comms/0.3.0",
+    e2ee: target.e2eePublicKeyB64 ? { enabled: true, daemonPublicKeyB64: target.e2eePublicKeyB64 } : undefined,
+    connectTimeoutMs: CONNECT_TIMEOUT_MS,
+    reconnect: { enabled: false },
+  });
+  try {
+    await withTimeout(client.connect(), CONNECT_TIMEOUT_MS, `connect ${target.name}`);
+    const peerServerId = client.getLastServerInfoMessage()?.serverId ?? null;
+    if (target.expectedServerId && peerServerId && peerServerId !== target.expectedServerId) {
+      throw new Error(`peer identity mismatch for '${target.name}': link reports ${peerServerId}`);
+    }
+    await withTimeout(
+      client.invokePluginRpc("x-comms", method, input),
+      CONNECT_TIMEOUT_MS,
+      `peer rpc ${method} ${target.name}`,
+    );
+    return { peerServerId };
+  } finally {
+    await client.close().catch((cause: unknown) => {
+      log.error(`peer close failed for '${target.name}': ${cause instanceof Error ? cause.message : String(cause)}`);
+    });
+  }
+}

package/server/peer-status.ts

@@ -0,0 +1,233 @@
+import { randomUUID } from "node:crypto";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { createPluginLogger } from "paseo-plugin-helper/server";
+import { withTimeout } from "paseo-plugin-helper/shared";
+import { currentRegistryPath, readRegistry } from "./registry";
+import { resolvePeerTarget } from "./peer-channel";
+
+const log = createPluginLogger("paseo-x-comms", { subsystem: "peer-status" });
+
+const PROBE_TIMEOUT_MS = 10_000;
+
+export interface RegistryDaemon {
+  name: string;
+  value: string;
+  valid: boolean;
+  error: string | null;
+}
+
+/**
+ * One row of the known-peer surface. Every field beyond reachability is
+ * best-effort: a peer that answers the handshake but not `daemon.get_status`
+ * still counts as up with only the handshake identity populated.
+ */
+export interface PeerStatusResult {
+  name: string;
+  value: string;
+  valid: boolean;
+  reachable: boolean;
+  error: string | null;
+  transport: "relay" | "direct" | "unknown";
+  serverId: string | null;
+  hostname: string | null;
+  version: string | null;
+  pid: number | null;
+  listen: string | null;
+  relayEnabled: boolean | null;
+  relayEndpoint: string | null;
+  providerCount: number | null;
+  providersAvailable: number | null;
+  hubState: string | null;
+  hubDaemonId: string | null;
+  hubOrigin: string | null;
+  hubLastError: string | null;
+}
+
+function nullableString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function nullableNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function unreachableResult(
+  daemon: RegistryDaemon,
+  transport: PeerStatusResult["transport"],
+  error: string,
+): PeerStatusResult {
+  return {
+    name: daemon.name,
+    value: daemon.value,
+    valid: daemon.valid,
+    reachable: false,
+    error,
+    transport,
+    serverId: null,
+    hostname: null,
+    version: null,
+    pid: null,
+    listen: null,
+    relayEnabled: null,
+    relayEndpoint: null,
+    providerCount: null,
+    providersAvailable: null,
+    hubState: null,
+    hubDaemonId: null,
+    hubOrigin: null,
+    hubLastError: null,
+  };
+}
+
+/** Relay block from a `daemon.get_status` payload (object form, not the CLI string). */
+export function mapRelayStatus(raw: unknown): { enabled: boolean | null; endpoint: string | null } {
+  if (!raw || typeof raw !== "object") return { enabled: null, endpoint: null };
+  const relay = raw as Record<string, unknown>;
+  return {
+    enabled: typeof relay.enabled === "boolean" ? relay.enabled : null,
+    endpoint: nullableString(relay.publicEndpoint) ?? nullableString(relay.endpoint),
+  };
+}
+
+export function mapProviderCounts(raw: unknown): { total: number | null; available: number | null } {
+  if (!Array.isArray(raw)) return { total: null, available: null };
+  return {
+    total: raw.length,
+    available: raw.filter((provider) => (provider as { available?: unknown })?.available === true).length,
+  };
+}
+
+export function mapHubStatus(raw: unknown): Pick<PeerStatusResult, "hubState" | "hubDaemonId" | "hubOrigin" | "hubLastError"> {
+  const status = (raw as { status?: unknown })?.status;
+  if (!status || typeof status !== "object") {
+    return { hubState: null, hubDaemonId: null, hubOrigin: null, hubLastError: null };
+  }
+  const hub = status as Record<string, unknown>;
+  return {
+    hubState: nullableString(hub.state),
+    hubDaemonId: nullableString(hub.daemonId),
+    hubOrigin: nullableString(hub.hubOrigin),
+    hubLastError: nullableString(hub.lastError),
+  };
+}
+
+export type PeerProber = (daemon: RegistryDaemon) => Promise<PeerStatusResult>;
+
+/**
+ * Probe every daemon concurrently. A thrown prober is converted to a down
+ * entry, so one unreachable peer can never fail the whole surface.
+ */
+export async function collectPeerStatus(
+  daemons: RegistryDaemon[],
+  prober: PeerProber,
+): Promise<{ results: PeerStatusResult[] }> {
+  const results = await Promise.all(
+    daemons.map(async (daemon) => {
+      try {
+        return await prober(daemon);
+      } catch (cause) {
+        return unreachableResult(daemon, "unknown", cause instanceof Error ? cause.message : String(cause));
+      }
+    }),
+  );
+  return { results };
+}
+
+/**
+ * Dial a registered peer and read its own `daemon.get_status` (identity,
+ * listen, relay, providers) plus a best-effort hub relationship. The
+ * registry endpoint is resolved the same way presence uses it, so an
+ * undialable endpoint surfaces as down rather than throwing.
+ */
+export const probePeer: PeerProber = async (daemon) => {
+  if (!daemon.valid) {
+    return unreachableResult(daemon, "unknown", daemon.error ?? "invalid registry entry");
+  }
+  let target;
+  try {
+    target = resolvePeerTarget(daemon.name, daemon.value);
+  } catch (cause) {
+    return unreachableResult(daemon, "unknown", cause instanceof Error ? cause.message : String(cause));
+  }
+  const transport = target.expectedServerId ? "relay" : "direct";
+
+  const client = new DaemonClient({
+    url: target.url,
+    clientId: randomUUID(),
+    clientType: "cli",
+    appVersion: "paseo-x-comms/0.3.0",
+    e2ee: target.e2eePublicKeyB64 ? { enabled: true, daemonPublicKeyB64: target.e2eePublicKeyB64 } : undefined,
+    connectTimeoutMs: PROBE_TIMEOUT_MS,
+    reconnect: { enabled: false },
+  });
+
+  try {
+    await withTimeout(client.connect(), PROBE_TIMEOUT_MS, `connect ${daemon.name}`);
+    const handshake = client.getLastServerInfoMessage();
+    const handshakeServerId = handshake?.serverId ?? null;
+    if (target.expectedServerId && handshakeServerId && handshakeServerId !== target.expectedServerId) {
+      return unreachableResult(
+        daemon,
+        transport,
+        `peer identity mismatch: link reports ${handshakeServerId}`,
+      );
+    }
+
+    const result: PeerStatusResult = {
+      ...unreachableResult(daemon, transport, ""),
+      reachable: true,
+      error: null,
+      serverId: handshakeServerId,
+      hostname: nullableString(handshake?.hostname),
+      version: nullableString(handshake?.version),
+    };
+
+    // Identity from the peer's own status is authoritative when available; a
+    // peer that does not implement the RPC is still up via the handshake.
+    try {
+      const status = await withTimeout(
+        client.getDaemonStatus({ timeout: PROBE_TIMEOUT_MS }),
+        PROBE_TIMEOUT_MS,
+        `daemon status ${daemon.name}`,
+      );
+      const relay = mapRelayStatus(status.relay);
+      const providers = mapProviderCounts(status.providers);
+      result.serverId = nullableString(status.serverId) ?? result.serverId;
+      result.version = nullableString(status.version) ?? result.version;
+      result.pid = nullableNumber(status.pid);
+      result.listen = nullableString(status.listen);
+      result.relayEnabled = relay.enabled;
+      result.relayEndpoint = relay.endpoint;
+      result.providerCount = providers.total;
+      result.providersAvailable = providers.available;
+    } catch (cause) {
+      log.warn(
+        `peer status for '${daemon.name}' unavailable, using handshake identity: ${cause instanceof Error ? cause.message : String(cause)}`,
+      );
+    }
+
+    try {
+      Object.assign(result, mapHubStatus(await withTimeout(client.getHubStatus(), PROBE_TIMEOUT_MS, `hub status ${daemon.name}`)));
+    } catch {
+      // Hub relationship is optional; peers without hub support stay null.
+    }
+
+    return result;
+  } catch (cause) {
+    return unreachableResult(daemon, transport, cause instanceof Error ? cause.message : String(cause));
+  } finally {
+    await client.close().catch((cause: unknown) => {
+      log.error(`peer close failed for '${daemon.name}': ${cause instanceof Error ? cause.message : String(cause)}`);
+    });
+  }
+};
+
+/** Registry read + live per-peer probe; the handler the client surface calls. */
+export async function handlePeerStatus(
+  _input?: unknown,
+  _context?: unknown,
+  prober: PeerProber = probePeer,
+): Promise<{ results: PeerStatusResult[] }> {
+  const current = readRegistry(currentRegistryPath());
+  return collectPeerStatus(current.ok ? current.daemons : [], prober);
+}

package/server/presence.ts

@@ -0,0 +1,204 @@
+import { PluginStorage } from "paseo-plugin-helper/server";
+
+/**
+ * Presence store (mesh Layer 1, control plane only).
+ *
+ * Vocabulary follows docs/mesh.md: announce (birth), retract, tombstones.
+ * Live entries are keyed by (serverId, agentId). Identity is never trusted
+ * from a payload alone: receivers only accept entries whose serverId matches
+ * an explicitly paired peer (seed links stay explicit).
+ *
+ * Anti-loop rules, in order of importance:
+ * 1. Seen-id LRU, bounded: duplicates are dropped on arrival.
+ * 2. Never forward gossip: only locally-originated events leave this daemon.
+ *    Enforced by origin tracking plus a relay filter at the transport edge.
+ * 3. Retract-before-reannounce with sticky tombstones: a birth older than
+ *    (or simultaneous with) its tombstone is refused, so delayed births
+ *    cannot resurrect the dead.
+ * 4. TTL is purely a safety net: expiry sweeps live entries and reports an
+ *    alert so a real bug surfaces instead of silently healing.
+ */
+
+export interface PresenceBirth {
+  serverId: string;
+  agentId: string;
+  name: string;
+  provider: string;
+  timestamp: string;
+}
+
+export interface PresenceLiveEntry extends PresenceBirth {
+  origin: "local" | "remote";
+  lastSeenAt: string;
+}
+
+export interface PresenceTombstone {
+  serverId: string;
+  agentId: string;
+  retractedAt: string;
+}
+
+export interface PendingRetract {
+  peer: string;
+  serverId: string;
+  agentId: string;
+  timestamp: string;
+  messageId: string;
+  queuedAt: string;
+  attempts: number;
+}
+
+export interface PresenceState {
+  live: Record<string, PresenceLiveEntry>;
+  tombstones: Record<string, PresenceTombstone>;
+  seenIds: string[];
+  pendingRetracts: PendingRetract[];
+}
+
+export const PRESENCE_SEEN_CAP = 1000;
+export const PRESENCE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const PRESENCE_TOMBSTONE_TTL_MS = 2 * PRESENCE_TTL_MS;
+
+export function presenceKey(serverId: string, agentId: string): string {
+  return `${serverId}/${agentId}`;
+}
+
+export function emptyPresenceState(): PresenceState {
+  return { live: {}, tombstones: {}, seenIds: [], pendingRetracts: [] };
+}
+
+function noteSeen(state: PresenceState, messageId: string): boolean {
+  if (state.seenIds.includes(messageId)) return false;
+  state.seenIds.push(messageId);
+  while (state.seenIds.length > PRESENCE_SEEN_CAP) state.seenIds.shift();
+  return true;
+}
+
+export type AnnounceOutcome =
+  | { result: "accepted" }
+  | { result: "duplicate" }
+  | { result: "refused-tombstoned" }
+  | { result: "refused-stale" };
+
+/**
+ * Apply one birth announcement. Returns the outcome; mutates state.
+ * `nowIso` is injectable for tests.
+ */
+export function applyAnnounce(
+  state: PresenceState,
+  birth: PresenceBirth,
+  messageId: string,
+  origin: "local" | "remote",
+  nowIso: string = new Date().toISOString(),
+): AnnounceOutcome {
+  if (!noteSeen(state, messageId)) return { result: "duplicate" };
+  const key = presenceKey(birth.serverId, birth.agentId);
+  const tombstone = state.tombstones[key];
+  if (tombstone && birth.timestamp <= tombstone.retractedAt) {
+    return { result: "refused-tombstoned" };
+  }
+  if (tombstone) delete state.tombstones[key];
+  const existing = state.live[key];
+  if (existing && birth.timestamp <= existing.timestamp) {
+    return { result: "refused-stale" };
+  }
+  state.live[key] = { ...birth, origin, lastSeenAt: nowIso };
+  return { result: "accepted" };
+}
+
+export type RetractOutcome = { applied: boolean; duplicate: boolean };
+
+/**
+ * Apply one retract. Always tombstones, even if no live entry exists, so a
+ * delayed birth arriving later is refused. Mutates state.
+ */
+export function applyRetract(
+  state: PresenceState,
+  serverId: string,
+  agentId: string,
+  timestamp: string,
+  messageId: string,
+): RetractOutcome {
+  if (!noteSeen(state, messageId)) return { applied: false, duplicate: true };
+  const key = presenceKey(serverId, agentId);
+  delete state.live[key];
+  const prev = state.tombstones[key];
+  if (!prev || timestamp > prev.retractedAt) {
+    state.tombstones[key] = { serverId, agentId, retractedAt: timestamp };
+  }
+  return { applied: true, duplicate: false };
+}
+
+/**
+ * Relay filter for the transport edge: only locally-originated live entries
+ * may leave this daemon. Everything received via gossip stays local.
+ */
+export function localLiveEntries(state: PresenceState): PresenceLiveEntry[] {
+  return Object.values(state.live).filter((entry) => entry.origin === "local");
+}
+
+/**
+ * TTL sweep. Returns expired live keys and stale tombstone keys, and mutates
+ * state by removing them. Callers must treat any non-empty result as an
+ * alert: TTL firing means announcements or retracts stopped flowing.
+ */
+export function sweepExpired(
+  state: PresenceState,
+  nowMs: number = Date.now(),
+): { expiredLive: string[]; expiredTombstones: string[] } {
+  const expiredLive: string[] = [];
+  for (const [key, entry] of Object.entries(state.live)) {
+    if (nowMs - Date.parse(entry.lastSeenAt) > PRESENCE_TTL_MS) {
+      delete state.live[key];
+      expiredLive.push(key);
+    }
+  }
+  const expiredTombstones: string[] = [];
+  for (const [key, tomb] of Object.entries(state.tombstones)) {
+    if (nowMs - Date.parse(tomb.retractedAt) > PRESENCE_TOMBSTONE_TTL_MS) {
+      delete state.tombstones[key];
+      expiredTombstones.push(key);
+    }
+  }
+  return { expiredLive, expiredTombstones };
+}
+
+export function queueRetract(
+  state: PresenceState,
+  pending: PendingRetract,
+): void {
+  const key = presenceKey(pending.serverId, pending.agentId);
+  state.pendingRetracts = state.pendingRetracts.filter(
+    (p) => p.peer !== pending.peer || presenceKey(p.serverId, p.agentId) !== key,
+  );
+  state.pendingRetracts.push(pending);
+}
+
+export function pendingForPeer(state: PresenceState, peer: string): PendingRetract[] {
+  return state.pendingRetracts.filter((p) => p.peer === peer);
+}
+
+const presenceStore = new PluginStorage<PresenceState>("paseo-x-comms", "presence.json", {
+  defaultData: emptyPresenceState(),
+});
+
+export function readPresence(): PresenceState {
+  try {
+    const data = presenceStore.read();
+    if (data && typeof data === "object") {
+      return {
+        live: data.live ?? {},
+        tombstones: data.tombstones ?? {},
+        seenIds: Array.isArray(data.seenIds) ? data.seenIds : [],
+        pendingRetracts: Array.isArray(data.pendingRetracts) ? data.pendingRetracts : [],
+      };
+    }
+  } catch {
+    // Corrupt state falls back to empty; gossip rebuilds it.
+  }
+  return emptyPresenceState();
+}
+
+export function writePresence(state: PresenceState): void {
+  presenceStore.write(state);
+}