@xpufx/paseo-x-comms 0.3.0

package/mcp/test/fixtures/extensions/transform/10-transform.mjs

@@ -0,0 +1,15 @@
+// Test fixture: exercises all three filters, using both the bare-return and the
+// explicit { action: "transform" } result forms.
+export default function register(api) {
+  api.onToolCall((args, context) => {
+    if (context.tool !== "x_comms_inspect") return undefined;
+    return { ...args, agentId: `${args.agentId}-rewritten` };
+  });
+
+  api.onSend((message) => ({ ...message, prompt: `[EXT] ${message.prompt}` }));
+
+  api.onReceive((data, context) => {
+    if (context.tool !== "x_comms_inspect") return undefined;
+    return { action: "transform", value: { ...data, extTag: "seen" } };
+  });
+}

package/mcp/test/fixtures/fake-paseo.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// Hermetic stand-in for the paseo CLI. Only used by tests via PASEO_X_COMMS_PASEO.
+// Never called by the real tool outside of tests.
+//
+// Test controls via env:
+//   FAKE_PASEO_DELAY_MS  respond after a delay (tests cancellation / exit discipline)
+//   FAKE_PASEO_FAIL      exit 1 with this message on stderr (tests error paths)
+import { setTimeout as sleep } from "node:timers/promises";
+
+const args = process.argv.slice(2);
+const delay = Number(process.env.FAKE_PASEO_DELAY_MS || 0);
+const fail = process.env.FAKE_PASEO_FAIL;
+
+function argAfter(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] ?? null : null;
+}
+
+const sub = args[0];
+const host = argAfter("--host");
+const prompt = args[args.length - 1];
+
+function respond(data) {
+  if (delay > 0) {
+    // Keep the event loop alive across the delay; SIGTERM still kills us (no
+    // signal listener installed), which is what the cancellation test relies on.
+    sleep(delay).then(() => write(data));
+  } else {
+    write(data);
+  }
+}
+function write(data) {
+  process.stdout.write(JSON.stringify(data) + "\n");
+}
+
+if (fail) {
+  console.error(fail);
+  process.exit(1);
+}
+
+switch (sub) {
+  case "daemon":
+    respond({ serverId: "srv_fake", hostname: "fakehost" });
+    break;
+  case "inspect":
+    respond({ Id: args[1], Name: "fake-agent", sawHost: host });
+    break;
+  case "ls":
+    respond([{ id: "agent-1", shortId: "agent-1", name: "fake-agent", status: "idle", sawHost: host }]);
+    break;
+  case "send":
+    respond({ ok: true, to: args[1], sawHost: host, sawNoWait: args.includes("--no-wait"), promptHead: prompt });
+    break;
+  case "logs":
+    respond({ events: [], sawHost: host });
+    break;
+  case "wait":
+    respond({
+      agentId: args[1],
+      status: process.env.FAKE_PASEO_WAIT_STATUS || "idle",
+      message: process.env.FAKE_PASEO_WAIT_STATUS === "permission"
+        ? "Agent is waiting for permission: external_directory"
+        : "Agent is idle.",
+      sawHost: host,
+      sawTimeout: argAfter("--timeout"),
+    });
+    break;
+  case "permit": {
+    const sub = args[1];
+    if (sub === "ls") {
+      respond(process.env.FAKE_PASEO_PERMISSIONS ? JSON.parse(process.env.FAKE_PASEO_PERMISSIONS) : []);
+    } else if (sub === "allow" || sub === "deny") {
+      // positional agent is args[2]; positional reqId is args[3] (if no options before it)
+      const positionals = args.slice(2).filter((a) => !a.startsWith("-"));
+      const item = {
+        requestId: positionals[1] ?? "all",
+        agentId: positionals[0],
+        result: sub === "allow" ? "allowed" : "denied",
+        sawHost: host,
+        sawAll: args.includes("--all"),
+      };
+      respond(sub === "allow" ? [item] : { data: [item] });
+    } else {
+      console.error(`fake-paseo: unhandled permit subcommand: ${sub}`);
+      process.exit(1);
+    }
+    break;
+  }
+  default:
+    console.error(`fake-paseo: unhandled args: ${args.join(" ")}`);
+    process.exit(1);
+}

package/mcp/test/register-ts-hooks.mjs

@@ -0,0 +1,6 @@
+// Registered via `node --import` (see package.json test script): installs the
+// TS-extension resolve hooks for the test process. Separate file because a
+// hooks module must be registered, not merely imported.
+import { register } from "node:module";
+
+register("./resolve-ts-hooks.mjs", import.meta.url);

package/mcp/test/resolve-ts-hooks.mjs

@@ -0,0 +1,46 @@
+// Dev-only ESM resolution hook for `node --test` (see package.json test script).
+// The vendored helper (client/server/shared/vendor/paseo-plugin-helper/) uses
+// extensionless relative imports, which the daemon's esbuild bundler and tsc
+// resolve fine but plain node (type-stripping, no loader) does not. This hook
+// maps extensionless relative specifiers to their .ts/.tsx/index files.
+// Track B of issue #71 (plugin #101).
+import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const EXTENSIONS = [".ts", ".tsx"];
+const INDEXES = ["index.ts", "index.tsx"];
+
+function tryFile(url) {
+  try {
+    if (fs.statSync(url, { throwIfNoEntry: false })?.isFile()) return url.href;
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+export async function resolve(specifier, context, next) {
+  try {
+    return await next(specifier, context);
+  } catch (err) {
+    if (
+      err?.code !== "ERR_MODULE_NOT_FOUND" ||
+      !specifier.startsWith(".") ||
+      /\.[a-z]+$/i.test(specifier)
+    ) {
+      throw err;
+    }
+    const parentPath = fileURLToPath(context.parentURL);
+    const base = new URL(specifier, pathToFileURL(parentPath));
+    const basePath = base.pathname;
+    for (const ext of EXTENSIONS) {
+      const hit = tryFile(new URL(`file://${basePath}${ext}`));
+      if (hit) return { url: hit, shortCircuit: true };
+    }
+    for (const index of INDEXES) {
+      const hit = tryFile(new URL(`file://${basePath}/${index}`));
+      if (hit) return { url: hit, shortCircuit: true };
+    }
+    throw err;
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@xpufx/paseo-x-comms",
+  "version": "0.3.0",
+  "description": "Cross-daemon agent conversation over Paseo Relay: a Paseo plugin that bundles the MCP server so agents on one daemon can talk to agents on another (relay offer or direct host).",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "paseo-x-comms": "./mcp/paseo-x-comms.mjs"
+  },
+  "scripts": {
+    "stamp": "node -e \"import('./server/vendor/paseo-plugin-helper/version.ts').then(m => m.stampVersion({ targetFile: 'shared/version.ts' }))\"",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import ./mcp/test/register-ts-hooks.mjs --test mcp/test/protocol.test.mjs server/presence.test.ts server/outbox.test.ts server/injection.test.ts server/settings.test.ts server/server-status.test.ts server/relay-status.test.ts server/conversations-snapshot.test.ts server/local-send.test.ts server/peer-status.test.ts client/tool-call.test.ts client/conversation-threads.test.ts client/attribution.test.ts client/message-direction.test.ts"
+  },
+  "keywords": [
+    "paseo",
+    "mcp",
+    "agent",
+    "relay",
+    "e2ee",
+    "daemon",
+    "cross-daemon",
+    "plugin"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@getpaseo/client": "0.9.0-beta.2",
+    "@getpaseo/protocol": "0.9.0-beta.2",
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "@getpaseo/plugin": "0.9.0-beta.2",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/react": "^19.0.10",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xpufx/paseo.git"
+  },
+  "files": [
+    "paseo-plugin.json",
+    "README.md",
+    "LICENSE",
+    "client",
+    "server",
+    "shared",
+    "mcp",
+    "docs",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/*.test.mjs",
+    "!**/.DS_Store"
+  ]
+}

package/paseo-plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "x-comms",
+  "requirements": { "paseo": ">=0.8.0" },
+  "build": [
+    ["npm", "install", "--omit=dev", "--no-audit", "--no-fund", "--no-workspaces"]
+  ]
+}

package/server/conversations-snapshot.ts

@@ -0,0 +1,249 @@
+import { PluginStorage } from "paseo-plugin-helper/server";
+import {
+  emptyConversationsSnapshot,
+  type XCommsConversationsSnapshot,
+  type XCommsThreadSnapshot,
+} from "../shared/conversations-snapshot.ts";
+import { parseEnvelope } from "../shared/envelope.ts";
+
+/**
+ * Conversations snapshot writer (mesh visibility input). Daemon-local view
+ * of active x-comms threads, maintained without timeline polling by
+ * readers: writers update on send and on timeline reconcile (receive),
+ * readers consume the file. Plain data in, plain data out.
+ */
+
+export const CONVERSATIONS_SNAPSHOT_FILE = "conversations.json";
+export const CONVERSATIONS_THREAD_CAP = 200;
+
+export interface SendRecord {
+  peerAlias: string;
+  peerServerId: string;
+  peerAgentId: string;
+  peerAgentName: string | null;
+  localAgentId: string | null;
+  at: string;
+}
+
+export interface TimelineEntryLike {
+  item?: { type?: string; text?: string } | null;
+}
+
+export interface TimelineOwnerLike {
+  ownerAgentId: string;
+  entries: TimelineEntryLike[];
+}
+
+/**
+ * Minimal structural surface needed to scan local timelines. The real
+ * PaseoApi satisfies this; mocks in tests do too.
+ */
+export interface TimelineScanner {
+  agents: {
+    list(): Promise<{ entries: Array<{ agent: { id: string } }> }>;
+    ref(id: string): {
+      timeline: { refetch(): Promise<{ entries: Array<unknown> }> };
+    };
+  };
+}
+
+function asTimelineEntry(raw: unknown): TimelineEntryLike | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const item = (raw as { item?: unknown }).item;
+  if (typeof item !== "object" || item === null) return null;
+  const { type, text } = item as { type?: unknown; text?: unknown };
+  return {
+    item: {
+      type: typeof type === "string" ? type : undefined,
+      text: typeof text === "string" ? text : undefined,
+    },
+  };
+}
+
+/**
+ * Pull every local agent's timeline and keep entries that carry the
+ * x-comms envelope. Per-agent failures are skipped, never fatal.
+ */
+export async function scanLocalTimelines(scanner: TimelineScanner): Promise<TimelineOwnerLike[]> {
+  const listed = await scanner.agents.list();
+  const out: TimelineOwnerLike[] = [];
+  for (const { agent } of listed.entries) {
+    try {
+      const page = await scanner.agents.ref(agent.id).timeline.refetch();
+      const entries: TimelineEntryLike[] = [];
+      for (const raw of page.entries) {
+        const entry = asTimelineEntry(raw);
+        if (entry) entries.push(entry);
+      }
+      out.push({ ownerAgentId: agent.id, entries });
+    } catch {
+      continue;
+    }
+  }
+  return out;
+}
+
+function threadKey(peerServerId: string, peerAgentId: string): string {
+  return `${peerServerId}/${peerAgentId}`;
+}
+
+function withLocalAgentIds(existing: string[], agentId: string | null): string[] {
+  if (!agentId || existing.includes(agentId)) return existing;
+  return [...existing, agentId];
+}
+
+/**
+ * Record an outbound send. Sending implies caught-up: unread resets and the
+ * read watermark advances to now.
+ */
+export function recordSend(
+  snapshot: XCommsConversationsSnapshot,
+  send: SendRecord,
+): XCommsConversationsSnapshot {
+  const key = threadKey(send.peerServerId, send.peerAgentId);
+  const threads = snapshot.threads.filter((t) => threadKey(t.peerServerId, t.peerAgentId) !== key);
+  threads.push({
+    peerAlias: send.peerAlias,
+    peerServerId: send.peerServerId,
+    peerAgentId: send.peerAgentId,
+    peerAgentName: send.peerAgentName,
+    localAgentIds: withLocalAgentIds(
+      snapshot.threads.find((t) => threadKey(t.peerServerId, t.peerAgentId) === key)?.localAgentIds ?? [],
+      send.localAgentId,
+    ),
+    lastDirection: "outgoing",
+    lastTimestamp: send.at,
+    lastReadAt: send.at,
+    lastSeenAt: send.at,
+    unreadCount: 0,
+  });
+  return capThreads({ ...snapshot, threads, updatedAt: send.at });
+}
+
+/**
+ * Reconcile inbound envelopes found in local agents' timelines. Only
+ * messages newer than the thread's read watermark increment unread, so
+ * rescans never double-count.
+ */
+export function reconcileTimelines(
+  snapshot: XCommsConversationsSnapshot,
+  timelines: TimelineOwnerLike[],
+  peerAliasFor: (serverId: string) => string | null,
+  nowIso: string = new Date().toISOString(),
+): XCommsConversationsSnapshot {
+  let threads = [...snapshot.threads];
+  const upsert = (entry: Omit<XCommsThreadSnapshot, "localAgentIds" | "lastReadAt" | "lastSeenAt" | "unreadCount"> & {
+    localAgentId: string;
+  }) => {
+    const key = threadKey(entry.peerServerId, entry.peerAgentId);
+    const existing = threads.find((t) => threadKey(t.peerServerId, t.peerAgentId) === key);
+    if (!existing) {
+      threads.push({
+        ...entry,
+        localAgentIds: [entry.localAgentId],
+        lastReadAt: new Date(0).toISOString(),
+        lastSeenAt: entry.lastTimestamp,
+        unreadCount: 1,
+      });
+      return;
+    }
+    const fresh = entry.lastTimestamp > existing.lastReadAt && entry.lastTimestamp > existing.lastSeenAt;
+    const seenAt = entry.lastTimestamp > existing.lastSeenAt ? entry.lastTimestamp : existing.lastSeenAt;
+    threads = threads.map((t) =>
+      threadKey(t.peerServerId, t.peerAgentId) === key
+        ? {
+            ...t,
+            peerAlias: entry.peerAlias,
+            peerAgentName: entry.peerAgentName ?? t.peerAgentName,
+            localAgentIds: withLocalAgentIds(t.localAgentIds, entry.localAgentId),
+            lastDirection: "incoming",
+            lastTimestamp: entry.lastTimestamp > t.lastTimestamp ? entry.lastTimestamp : t.lastTimestamp,
+            lastSeenAt: seenAt,
+            unreadCount: fresh ? t.unreadCount + 1 : t.unreadCount,
+          }
+        : t,
+    );
+  };
+  for (const timeline of timelines) {
+    for (const entry of timeline.entries) {
+      const text = entry.item?.text;
+      if (!text) continue;
+      const parsed = parseEnvelope(text);
+      if (!parsed) continue;
+      const sender = parsed.envelope.xComms.sender;
+      if (!sender.agentId || !sender.daemonServerId) continue;
+      upsert({
+        peerAlias: peerAliasFor(sender.daemonServerId) ?? sender.host ?? "unknown",
+        peerServerId: sender.daemonServerId,
+        peerAgentId: sender.agentId,
+        peerAgentName: sender.agentName,
+        localAgentId: timeline.ownerAgentId,
+        lastDirection: "incoming",
+        lastTimestamp: parsed.envelope.xComms.sentAt,
+      });
+    }
+  }
+  return capThreads({ ...snapshot, threads, updatedAt: nowIso });
+}
+
+/**
+ * Drop threads for a peer agent that retracted (or whose link died).
+ * Returns true when anything was removed.
+ */
+export function prunePeer(
+  snapshot: XCommsConversationsSnapshot,
+  peerServerId: string,
+  peerAgentId: string,
+): { snapshot: XCommsConversationsSnapshot; removed: boolean } {
+  const key = threadKey(peerServerId, peerAgentId);
+  const threads = snapshot.threads.filter((t) => threadKey(t.peerServerId, t.peerAgentId) !== key);
+  return { snapshot: { ...snapshot, threads }, removed: threads.length !== snapshot.threads.length };
+}
+
+/**
+ * Detach a local agent (archive): remove it from every thread's local
+ * participants, dropping threads with nobody left.
+ */
+export function detachLocalAgent(
+  snapshot: XCommsConversationsSnapshot,
+  localAgentId: string,
+): { snapshot: XCommsConversationsSnapshot; removed: boolean } {
+  const threads = snapshot.threads
+    .map((t) => ({ ...t, localAgentIds: t.localAgentIds.filter((id) => id !== localAgentId) }))
+    .filter((t) => t.localAgentIds.length > 0);
+  return { snapshot: { ...snapshot, threads }, removed: threads.length !== snapshot.threads.length };
+}
+
+function capThreads(snapshot: XCommsConversationsSnapshot): XCommsConversationsSnapshot {
+  if (snapshot.threads.length <= CONVERSATIONS_THREAD_CAP) return snapshot;
+  const threads = [...snapshot.threads]
+    .sort((a, b) => (a.lastTimestamp < b.lastTimestamp ? 1 : -1))
+    .slice(0, CONVERSATIONS_THREAD_CAP);
+  return { ...snapshot, threads };
+}
+
+const conversationsStore = new PluginStorage<XCommsConversationsSnapshot>(
+  "paseo-x-comms",
+  CONVERSATIONS_SNAPSHOT_FILE,
+  { defaultData: emptyConversationsSnapshot() },
+);
+
+export function conversationsSnapshotPath(): string {
+  return conversationsStore.filePath;
+}
+
+export function readConversationsSnapshot(): XCommsConversationsSnapshot {
+  try {
+    const data = conversationsStore.read();
+    if (data && typeof data === "object" && Array.isArray((data as { threads?: unknown }).threads)) {
+      return data as XCommsConversationsSnapshot;
+    }
+  } catch {
+    // Corrupt state falls back to empty; writers rebuild it.
+  }
+  return emptyConversationsSnapshot();
+}
+
+export function writeConversationsSnapshot(snapshot: XCommsConversationsSnapshot): void {
+  conversationsStore.write(snapshot);
+}