@xpufx/paseo-x-comms 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xpufx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# paseo-x-comms
+
+> **⚠️ WIP — use at your own risk.** Not release-ready; APIs and behavior may change without notice.
+
+> Tracks stable paseo (`@getpaseo/* 0.8.0`, manifest requires `paseo >= 0.8.0`). Expect breaking changes between versions.
+
+[paseo](https://paseo.sh) is an agent orchestrator: AI coding agents run on paseo daemons, each managing workspaces, tools, and permissions. **paseo-x-comms** lets agents on one daemon talk to agents on another — even across hosts — via the daemon relay (WebSocket + E2EE) or direct TCP.
+
+Scope: x-comms links one owner's daemons through one client UI. Pairing is explicit and local; stranger federation is out of scope (an experimental flag at most, post-1.0).
+
+Built on [paseo-plugin-helper](https://github.com/xpufx/paseo/tree/main/packages/paseo-plugin-helper), the shared Paseo plugin runtime.
+
+This repo ships two things:
+
+* **Paseo plugin** (recommended) — UI + embedded MCP server. (This README is for the plugin. See below)
+* **Standalone MCP server** (`mcp/`) — the same server without the paseo plugin. See **[mcp/README.md](mcp/README.md)** for its standalone install, tool reference, and protocol details.
+
+## Plugin
+
+The plugin embeds the MCP server and adds the X-comms UI. Agents get `x_comms_*` tools automatically; humans get surfaces to manage daemons and conversations.
+
+### What you get
+
+* **Main surface — X-comms** (`client/main.tsx`, surfaced via `index.client.tsx` sidebar item): registered daemons list with health (reachable/unreachable + agent count), add/edit/remove with host-form validation and reachability probe, refresh (identity + snapshot), server version check, introduce-agents picker, debug dump per daemon.
+* **Peers surface** (`client/peer-status.tsx`, the "Peers" tab): the known daemon registry rendered with a live per-peer `daemon.get_status` probe — up/down plus identity (`serverId`, `version`, `listen`, relay, provider count, hub relationship). Each host is probed independently (relay or direct), so an unreachable peer shows as down without failing the surface. Polls every 30 s via `peer.status`.
+* **Composer pill** (`client/x-comms-pill.tsx`): one `X-comms` pill per agent in the composer; opens the conversation panel for that agent.
+* **Agent panel** (`client/x-comms-panel.tsx` / `x-comms-timeline.tsx` / `x-comms-conversation.tsx`, plus `x-comms-tool-call.tsx` and `via-x-comms.tsx`): per-agent conversation view with timeline rendering of the `[x-comms]` envelope, send/reply, wait, and permission handling. Timeline transformers/renderers registered in `index.client.tsx` render envelopes and tool calls inline in agent timelines.
+* **Server side** (`index.server.ts` + `server/`): registry, health, settings, presence announce/retract/list, and MCP injection handlers.
+* **Embedded MCP server** (`mcp/paseo-x-comms.mjs`): spawned via `serverPath()` from `server/server-status.ts` (resolved from `import.meta.url` with plugin-dir fallbacks); shares the repo-root `node_modules` — no separate install or `paseo` on PATH required beyond the daemon itself.
+
+### Install
+
+The plugin lives at the repo root (`paseo-plugin.json` id `x-comms`):
+
+```sh
+paseo plugin add xpufx/paseo-x-comms
+```
+
+The plugin requires **npm** and **Node.js** (v18+) in `$PATH`: the server bundle uses `@getpaseo/client` and `@getpaseo/protocol`, so `paseo-plugin.json` declares `npm install` as its install build command. `paseo-plugin-helper` is vendored under `client/`, `server/`, `shared/` and bundled from source. The MCP server is spawned from `./mcp` and resolves its deps (`@modelcontextprotocol/sdk`, `zod`, etc.) from the installed tree.
+
+To update:
+
+```sh
+paseo plugin update x-comms
+```
+
+### Configure daemons
+
+The registry is at `~/.paseo/paseo-x-comms/registry.json`:
+
+```json
+{
+  "home": "https://app.paseo.sh/#offer=<b64>",
+  "office": "10.0.0.5:6767"
+}
+```
+
+* Value is an **opaque `--host` string** — paseo classifies it. `https://app.paseo.sh/#offer=…` is a relay connection (E2EE); anything else (`host:port`, `tcp://…`, `unix://…`, IPC path, bare port) is a direct connection. See [mcp/README.md#host-forms](mcp/README.md#host-forms).
+* Manage it from the plugin UI (Main surface) or via the MCP tools `x_comms_add_daemon` / `x_comms_remove_daemon` / `x_comms_list_daemons`.
+* The file holds live pairing offers (serverId, public keys, relay endpoints) — treat it as credentials, never commit it.
+
+Quick pairing:
+
+1. On the **target** daemon: `paseo daemon pair --json` → copy the `url` (`https://app.paseo.sh/#offer=…`). For a directly-reachable daemon, use its address instead.
+2. On **this** daemon: open the X-comms Main surface → *Add daemon* → paste the offer or address. The UI probes reachability before saving (with "Add anyway" for offline hosts).
+
+### How messaging works
+
+Every `x_comms_send` prepends one line:
+
+```
+[x-comms] {"xComms":{"version":4,"type":"x-comms.incoming_message","sender":{…},"target":{…},"sentAt":"…","direction":"outgoing"}}
+```
+
+`sender` (agentId, agentName, host, daemonServerId, cwd) + `target` (daemon, agentId) + `sentAt`. Prompt text stays prose after the envelope. Recipients parse the envelope and reply via `x_comms_send` to `sender.agentId` on the sender's daemon. Full envelope + permission loop documented in [mcp/README.md#message-envelope](mcp/README.md#message-envelope) and [mcp/README.md#behavior-notes](mcp/README.md#behavior-notes).
+
+Tools (via the embedded server) are `x_comms_list_daemons`, `x_comms_add_daemon`, `x_comms_remove_daemon`, `x_comms_list_agents`, `x_comms_inspect`, `x_comms_send`, `x_comms_logs`, `x_comms_wait`, `x_comms_list_permissions`, `x_comms_allow_permission`, `x_comms_deny_permission` — see [mcp/README.md#tools](mcp/README.md#tools) for the reference. The plugin's conversation/panel UI wraps `send`/`logs`/`wait`/permissions for interactive use.
+
+### Outbox: retry, expiry, notification
+
+The plugin server keeps an **outbox** (the plugin state dir's `outbox.json`) for messages whose send failed. Held messages are retried over the same `x_comms_send` path with exponential backoff (5s doubling to a 60s cap), swept on a 15s periodic pass, and retried immediately when a peer is observed reconnecting (health/snapshot reachability flip).
+
+A held message expires after **10 minutes** by default (configurable in the settings surface, `outboxExpirySeconds`, clamped to 10s–24h). On expiry the sender is notified by appending an `x-comms-outbox-notice` timeline item with the reason; the message is then dropped.
+
+**Idempotency is not implemented.** The conversation protocol has no message-UUID slot and the receiver keeps no seen-id set for messages, so a retry after an ambiguous failure (send succeeded, acknowledgement lost) can re-deliver. Adding it would need a wire-format change; tracked separately.
+
+
+## Repository layout
+
+```
+.
+├── index.client.tsx          # Paseo 0.8 client entry (surfaces, pill, panel, timeline renderers)
+├── index.server.ts           # Paseo 0.8 server entry (RPC + presence + injection handlers)
+├── client/
+│   ├── main.tsx              # Main surface (daemon registry + health + prompt)
+│   ├── x-comms-pill.tsx      # Composer pill → conversation panel
+│   ├── x-comms-panel.tsx     # Agent panel host
+│   ├── x-comms-timeline.tsx  # Timeline / envelope rendering
+│   ├── x-comms-conversation.tsx
+│   ├── x-comms-tool-call.tsx # Tool-call timeline rendering
+│   ├── via-x-comms.tsx
+│   ├── conversations.ts      # Conversation derive (shared with tests)
+│   ├── attribution.ts / peer-label.ts / tool-call.ts
+│   └── *.test.ts             # Client unit tests
+├── server/
+│   ├── handlers.ts           # RPC handlers (registry, probe, dump, etc.)
+│   ├── registry.ts           # Daemon registry + health
+│   ├── settings.ts           # Plugin settings storage
+│   ├── presence.ts           # Presence announce/retract/list
+│   ├── injection.ts          # MCP injection for agents
+│   ├── snapshot.ts / conversations-snapshot.ts
+│   ├── server-status.ts      # Embedded server path resolution
+│   ├── mcp-client.ts / peer-channel.ts
+│   └── *.test.ts             # Server unit tests
+├── shared/
+│   ├── envelope.ts           # Wire envelope schema ([x-comms] parsing)
+│   ├── registry.ts           # RPC definitions (zod)
+│   └── conversations-snapshot.ts
+├── mcp/
+│   ├── paseo-x-comms.mjs      # MCP server (also bin `paseo-x-comms`)
+│   ├── README.md              # standalone server docs
+│   └── test/protocol.test.mjs
+├── paseo-plugin.json         # id x-comms, requires paseo >= 0.8.0
+└── package.json               # single install at root for plugin + server
+```
+
+## Standalone MCP
+
+If you don't use the plugin, run the server directly:
+
+```sh
+npm install -g @xpufx/paseo-x-comms
+```
+
+Requires `paseo` CLI on PATH, Node ≥ 18. Full instructions, env overrides (`PASEO_X_COMMS_*`), and client registration examples (pi `mcp.json` vs opencode `opencode.jsonc`) are in **[mcp/README.md](mcp/README.md)**.
+
+## Development
+
+```sh
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # node --test across mcp, server, and client suites (hermetic protocol tests plus presence, injection, settings, snapshot, and conversation suites)
+```
+
+No live daemons, no real `~/.paseo/paseo-x-comms/registry.json` touched in tests (`PASEO_X_COMMS_REMOTES` / `PASEO_X_COMMS_PASEO` overrides).
+
+## License
+
+Apache-2.0.

package/client/attribution.ts

@@ -0,0 +1,7 @@
+/**
+ * Standing attribution rule: everything this plugin renders into shared
+ * Paseo surfaces must carry the plugin name so users never mistake plugin
+ * output for Paseo core. Pure constant lives here (importable from tests);
+ * the themed component lives in attribution.tsx.
+ */
+export const XCOMMS_VIA_LABEL = "via x-comms";

package/client/conversations.ts

@@ -0,0 +1,229 @@
+import { usePaseo } from "@getpaseo/plugin/client";
+import { parseEnvelope, viewerDirection, type CrossDaemonEnvelope } from "../shared/envelope.ts";
+import { isXCommsTool } from "./tool-call.ts";
+
+type PaseoApi = ReturnType<typeof usePaseo>;
+
+export interface ConversationPartner {
+  conversationId: string;
+  // The counterparty this agent is talking to, derived from the envelope.
+  counterparty: {
+    daemon: string | null;
+    agentId: string | null;
+    agentName: string | null;
+    daemonServerId: string | null;
+  };
+  lastActivity: string;
+  messageCount: number;
+}
+
+export interface ConversationMessage {
+  id: string;
+  body: string;
+  sentAt: string;
+  isIncoming: boolean;
+  senderName: string | null;
+  daemon: string | null;
+  userSent?: boolean;
+}
+
+export interface ConversationThread {
+  partner: ConversationPartner;
+  messages: ConversationMessage[];
+}
+
+/**
+ * Single shared thread key. Derive and the peer picker must agree, or the
+ * merge site compares different strings and one side silently drops. The
+ * server id wins when present; the alias or host is the fallback.
+ */
+export function threadKeyForCounterparty(cp: {
+  daemon: string | null;
+  daemonServerId: string | null;
+  agentId: string | null;
+}): string {
+  return `${cp.daemonServerId ?? cp.daemon ?? "?"}/${cp.agentId ?? "?"}`;
+}
+
+/**
+ * Match two counterparties across alias vs serverId discrepancies.
+ */
+export function isCounterpartyMatch(
+  a: { daemon: string | null; daemonServerId?: string | null; agentId: string | null },
+  b: { daemon: string | null; daemonServerId?: string | null; agentId: string | null },
+): boolean {
+  if (!a.agentId || !b.agentId || a.agentId !== b.agentId) return false;
+  const aServer = a.daemonServerId ?? (a.daemon?.startsWith("srv_") ? a.daemon : null);
+  const bServer = b.daemonServerId ?? (b.daemon?.startsWith("srv_") ? b.daemon : null);
+  if (aServer && bServer) {
+    return aServer === bServer;
+  }
+  if (!aServer && !bServer && a.daemon && b.daemon) {
+    return a.daemon === b.daemon;
+  }
+  return true;
+}
+
+/**
+ * Interleave both directions by timestamp and deduplicate optimistic vs recorded sends.
+ */
+export function mergeMessages(
+  incoming: ConversationMessage[],
+  sent: ConversationMessage[],
+): ConversationMessage[] {
+  const seenIds = new Set<string>();
+  const out: ConversationMessage[] = [];
+  for (const m of [...incoming, ...sent]) {
+    if (seenIds.has(m.id)) continue;
+    const isDup = out.some(
+      (existing) =>
+        existing.body === m.body &&
+        existing.isIncoming === m.isIncoming &&
+        Math.abs(new Date(existing.sentAt).getTime() - new Date(m.sentAt).getTime()) < 3000,
+    );
+    if (!isDup) {
+      seenIds.add(m.id);
+      out.push(m);
+    }
+  }
+  return out.sort((a, b) => (a.sentAt < b.sentAt ? -1 : 1));
+}
+
+/**
+ * Derives the x-comms conversations an agent is part of by scanning its
+ * timeline for our meta envelopes. No separate ledger file: the timeline is the
+ * source of truth, so the result is never stale. Grouped by conversationId.
+ */
+export async function deriveConversations(
+  paseo: PaseoApi,
+  agentId: string,
+): Promise<ConversationPartner[]> {
+  const threads = await deriveConversationThreads(paseo, agentId);
+  return threads.map((t) => t.partner);
+}
+
+export async function deriveConversationThreads(
+  paseo: PaseoApi,
+  agentId: string,
+): Promise<ConversationThread[]> {
+  const handle = paseo.agents.ref(agentId);
+  const timeline = await handle.timeline.refetch();
+  const byConversation = new Map<string, ConversationThread>();
+
+  function addMessage(
+    counterparty: { daemon: string | null; agentId: string | null; agentName: string | null; daemonServerId: string | null },
+    msgData: Omit<ConversationMessage, "id"> & { id?: string },
+  ) {
+    const id = threadKeyForCounterparty(counterparty);
+    let thread = byConversation.get(id);
+    if (!thread) {
+      for (const t of byConversation.values()) {
+        if (isCounterpartyMatch(t.partner.counterparty, counterparty)) {
+          thread = t;
+          break;
+        }
+      }
+    }
+    if (!thread) {
+      thread = {
+        partner: {
+          conversationId: id,
+          counterparty,
+          lastActivity: msgData.sentAt,
+          messageCount: 0,
+        },
+        messages: [],
+      };
+      byConversation.set(id, thread);
+    }
+    const msgId = msgData.id ?? `${thread.partner.conversationId}-${msgData.sentAt}-${thread.messages.length}`;
+    thread.messages.push({ ...msgData, id: msgId });
+    thread.partner.messageCount += 1;
+    if (msgData.sentAt > thread.partner.lastActivity) {
+      thread.partner.lastActivity = msgData.sentAt;
+    }
+  }
+
+  for (const entry of timeline.entries) {
+    const item = entry.item as { type?: string; text?: string; name?: string; detail?: unknown } | undefined;
+    if (!item) continue;
+
+    // Case 1: user_message or assistant_message carrying [x-comms] wire envelope
+    if (item.type === "user_message" || item.type === "assistant_message") {
+      const text = item.text;
+      if (!text) continue;
+      const parsed = parseEnvelope(text);
+      if (!parsed) continue;
+      const env: CrossDaemonEnvelope = parsed.envelope;
+      const meta = env.xComms;
+      const isIncoming = viewerDirection(env, agentId) === "incoming";
+      const daemon = isIncoming
+        ? (meta.sender.daemonServerId ?? meta.sender.host ?? null)
+        : (meta.target.daemon ?? null);
+      const counterparty = isIncoming
+        ? {
+            daemon,
+            agentId: meta.sender.agentId ?? null,
+            agentName: meta.sender.agentName ?? null,
+            daemonServerId: meta.sender.daemonServerId ?? null,
+          }
+        : {
+            daemon,
+            agentId: meta.target.agentId ?? null,
+            agentName: null,
+            daemonServerId: daemon && daemon.startsWith("srv_") ? daemon : null,
+          };
+      const senderName = isIncoming
+        ? (meta.sender.agentName ?? meta.sender.agentId ?? "peer")
+        : "You";
+      addMessage(counterparty, {
+        body: parsed.body,
+        sentAt: meta.sentAt,
+        isIncoming,
+        senderName,
+        daemon,
+        userSent: !isIncoming,
+      });
+      continue;
+    }
+
+    // Case 2: tool_call invoking x_comms_send
+    if (item.type === "tool_call" || (item.name && isXCommsTool(item.name))) {
+      const name = item.name ?? "";
+      if (isXCommsTool(name) && name.includes("send")) {
+        const detail = item.detail as { input?: Record<string, unknown> } | undefined;
+        const input = detail && typeof detail === "object" ? detail.input : undefined;
+        if (input && typeof input === "object") {
+          const targetDaemon = typeof input.daemon === "string" ? input.daemon : null;
+          const targetAgentId = typeof input.agentId === "string" ? input.agentId : null;
+          const prompt = typeof input.prompt === "string" ? input.prompt : "";
+          if (targetAgentId) {
+            const daemonServerId = targetDaemon && targetDaemon.startsWith("srv_") ? targetDaemon : null;
+            const counterparty = {
+              daemon: targetDaemon,
+              agentId: targetAgentId,
+              agentName: null,
+              daemonServerId,
+            };
+            const sentAt = (entry as { timestamp?: string }).timestamp ?? new Date().toISOString();
+            const fromUser = input.fromAgentName === "User" || !input.fromAgentId || input.fromAgentId === agentId;
+            addMessage(counterparty, {
+              id: `tool-send-${targetAgentId}-${sentAt}-${prompt.slice(0, 8)}`,
+              body: prompt,
+              sentAt,
+              isIncoming: false,
+              senderName: fromUser ? "You" : (typeof input.fromAgentName === "string" ? input.fromAgentName : "Agent"),
+              daemon: targetDaemon,
+              userSent: fromUser,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  for (const thread of byConversation.values()) {
+    thread.messages.sort((a, b) => (a.sentAt < b.sentAt ? -1 : 1));
+  }
+  return [...byConversation.values()].sort((a, b) => (a.partner.lastActivity < b.partner.lastActivity ? 1 : -1));
+}