@xpufx/paseo-x-comms 0.3.0 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 > **⚠️ 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.
+> Tracks Paseo 0.9 (`@getpaseo/* 0.9.0-beta.2`, manifest requires `paseo >= 0.9.0-beta.2`) for multi-host APIs. 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.
 
@@ -36,7 +36,7 @@ The plugin lives at the repo root (`paseo-plugin.json` id `x-comms`):
 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.
+The plugin requires **npm** and **Node.js** (v18+) in `$PATH`, plus Paseo **0.9.0-beta.2 or later**: the server bundle uses `@getpaseo/client` and `@getpaseo/protocol`, so `paseo-plugin.json` declares its production-only, lifecycle-disabled `npm 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:
 
@@ -89,8 +89,8 @@ A held message expires after **10 minutes** by default (configurable in the sett
 
 ```
 .
-├── 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)
+├── index.client.tsx          # Paseo 0.9 client entry (surfaces, pill, panel, timeline renderers)
+├── index.server.ts           # Paseo 0.9 server entry (RPC + presence + injection handlers)
 ├── client/
 │   ├── main.tsx              # Main surface (daemon registry + health + prompt)
 │   ├── x-comms-pill.tsx      # Composer pill → conversation panel
@@ -120,7 +120,7 @@ A held message expires after **10 minutes** by default (configurable in the sett
 │   ├── 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
+├── paseo-plugin.json         # id x-comms, requires paseo >= 0.9.0-beta.2
 └── package.json               # single install at root for plugin + server
 ```
 

package/client/configured-hosts.ts

@@ -0,0 +1,64 @@
+import type { PaseoApi } from "@getpaseo/client";
+import type { PluginHostSummary } from "@getpaseo/plugin/client";
+
+export interface ConfiguredHostAgent {
+  serverId: string;
+  hostLabel: string;
+  agentId: string;
+  name: string;
+  status: string | null;
+}
+
+export interface ConfiguredHostAgents {
+  host: PluginHostSummary;
+  agents: ConfiguredHostAgent[];
+  error: string | null;
+}
+
+/** A host/agent pair is the fleet identity; agent ids are host-local. */
+export function configuredHostAgentKey(serverId: string, agentId: string): string {
+  return `${serverId}/${agentId}`;
+}
+
+/**
+ * Query only currently online configured hosts. Each call obtains a fresh
+ * borrowed API; callers must discard the result after a host-status change.
+ */
+export async function listConfiguredHostAgents(
+  hosts: readonly PluginHostSummary[],
+  getClient: (serverId: string) => PaseoApi,
+): Promise<ConfiguredHostAgents[]> {
+  return Promise.all(hosts.map(async (host) => {
+    if (host.status !== "online") return { host, agents: [], error: null };
+    try {
+      const result = await getClient(host.serverId).agents.list();
+      return {
+        host,
+        agents: result.entries.map(({ agent }) => ({
+          serverId: host.serverId,
+          hostLabel: host.label,
+          agentId: agent.id,
+          name: agent.title ?? agent.id,
+          status: agent.status ?? null,
+        })),
+        error: null,
+      };
+    } catch (cause) {
+      return { host, agents: [], error: cause instanceof Error ? cause.message : String(cause) };
+    }
+  }));
+}
+
+/**
+ * Native configured-host send. This deliberately gets exactly one freshly
+ * borrowed target handle and sends to that selected agent only—never a peer
+ * registry route and never a broadcast.
+ */
+export async function sendConfiguredHostAgent(args: {
+  serverId: string;
+  agentId: string;
+  message: string;
+  getClient: (serverId: string) => PaseoApi;
+}): Promise<void> {
+  await args.getClient(args.serverId).agents.ref(args.agentId).send(args.message);
+}

package/client/main.tsx

@@ -19,7 +19,7 @@ import {
   Tabs,
   TextInput,
   usePluginTheme,
-} from "paseo-plugin-helper/client";
+} from "./vendor/paseo-plugin-helper/index";
 import { formatPeerDisplay } from "./peer-label";
 import { PeerStatusSurface } from "./peer-status";
 import { SettingsPrototype } from "./settings-prototype";

package/client/peer-status.tsx

@@ -13,7 +13,7 @@ import {
   StatusDot,
   usePluginTheme,
   useRpcQuery,
-} from "paseo-plugin-helper/client";
+} from "./vendor/paseo-plugin-helper/index";
 import { formatPeerDisplay } from "./peer-label";
 import { ViaXComms } from "./via-x-comms";
 import { peerStatusRpc } from "../shared/registry";

package/client/settings-prototype.tsx

@@ -16,7 +16,7 @@ import {
   StatusDot,
   TextInput,
   Toggle,
-} from "paseo-plugin-helper/client";
+} from "./vendor/paseo-plugin-helper/index";
 import { formatPeerDisplay } from "./peer-label";
 import { ViaXComms } from "./via-x-comms";
 import {

package/client/vendor/paseo-plugin-helper/utils/clipboard.ts

@@ -24,16 +24,23 @@ export interface ClipboardEnvironment {
  * `react-native-web` `Clipboard.setString` reports success even when its
  * `document.execCommand("copy")` fails, which leaves the previous clipboard
  * item in place while the UI claims success (xpufx-org/paseo#278); it is only
- * usable off-DOM (native), where it is the real platform clipboard. In a DOM
- * the checked `execCommand` fallback is preferred to that unverifiable path.
+ * usable off-DOM (native), where it is the real platform clipboard. The same
+ * applies to any `setStringAsync` whose DOM fallback is that unverified
+ * `execCommand`. In a DOM the checked `execCommand` fallback is preferred to
+ * those unverifiable paths.
  */
 export function clipboardTierOrder(env: ClipboardEnvironment): ClipboardTier[] {
   const tiers: ClipboardTier[] = [];
   if (env.hasNavigatorClipboard) tiers.push("navigator");
   if (env.hasHostCopyText) tiers.push("host");
-  if (env.hasRnSetStringAsync) {
+  // On a DOM both RN-web paths are unverifiable: `setString` reports success
+  // even when its `execCommand` no-ops, and a `setStringAsync` that falls back
+  // to it does the same. Off-DOM they are the real native clipboard, so they
+  // lead there; on a DOM only the checked `execCommand` fallback is honest.
+  const rnDomOk = !env.isDom;
+  if (env.hasRnSetStringAsync && rnDomOk) {
     tiers.push("rnAsync");
-  } else if (env.hasRnClipboard && !env.isDom) {
+  } else if (env.hasRnClipboard && rnDomOk) {
     tiers.push("rnSync");
   }
   tiers.push("execCommand");

package/client/x-comms-conversation.tsx

@@ -1,18 +1,22 @@
-import { usePaseo, useRpc } from "@getpaseo/plugin/client";
+import { getPaseoClient, useHosts, usePaseo, useRpc } from "@getpaseo/plugin/client";
 import type { PluginTheme } from "@getpaseo/plugin";
 import { Modal, ScrollView } from "@getpaseo/plugin/client/react-native";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ActivityIndicator, Clipboard, Pressable, Text, View } from "react-native";
 import type { NativeScrollEvent, NativeSyntheticEvent, ScrollView as NativeScrollView, StyleProp, ViewStyle } from "react-native";
-import { ModalContent, TextInput } from "paseo-plugin-helper/client";
+import { ModalContent, TextInput } from "./vendor/paseo-plugin-helper/index";
+import { buildXCommsEnvelope } from "../shared/envelope";
 import { conversationSendRpc, introspectAgentsRpc, registryReadRpc } from "../shared/registry";
 import { deriveConversationThreads, deriveConversations, isCounterpartyMatch, mergeMessages, threadKeyForCounterparty, type ConversationMessage, type ConversationPartner, type ConversationThread } from "./conversations";
+import { listConfiguredHostAgents, sendConfiguredHostAgent } from "./configured-hosts";
 import { formatCounterparty, formatPeerDisplay, splitCounterparty, useCounterpartyLabel, usePeerDisplay, type CounterpartyRef } from "./peer-label";
 import { ViaXComms } from "./via-x-comms";
 
 const draftCache = new Map<string, string>();
-const targetCache = new Map<string, ConversationPartner | null>();
+type SelectedTarget = ConversationPartner & { configuredHostServerId?: string };
+
+const targetCache = new Map<string, SelectedTarget | null>();
 const sentCache = new Map<string, Map<string, ConversationMessage[]>>();
 
 function PeerText({ counterparty }: { counterparty: CounterpartyRef }) {
@@ -89,6 +93,9 @@ export function CrossDaemonConversation({
   onSent?: () => void;
 }) {
   const paseo = usePaseo();
+  // This hook is deliberately confined to the mounted client surface. Server,
+  // MCP, outbox, and peer-channel code retain their existing routes.
+  const hosts = useHosts();
   const callSend = useRpc(conversationSendRpc);
   const callIntrospect = useRpc(introspectAgentsRpc);
   const callRegistryRead = useRpc(registryReadRpc);
@@ -126,7 +133,7 @@ export function CrossDaemonConversation({
     [serverIdByName],
   );
   const [draft, setDraft] = useState(() => draftCache.get(agentId) ?? "");
-  const [target, setTarget] = useState<ConversationPartner | null>(() => targetCache.get(agentId) ?? null);
+  const [target, setTarget] = useState<SelectedTarget | null>(() => targetCache.get(agentId) ?? null);
   const [pickerOpen, setPickerOpen] = useState(false);
 
   const queryClient = useQueryClient();
@@ -146,18 +153,48 @@ export function CrossDaemonConversation({
     queryFn: () => callIntrospect({}),
     staleTime: 30000,
   });
+  const hostStatusKey = useMemo(
+    () => hosts.map((host) => [host.serverId, host.status] as const),
+    [hosts],
+  );
+  const configuredHosts = useQuery({
+    queryKey: ["x-comms-configured-hosts", hostStatusKey],
+    // getPaseoClient is called only in this query, when the host is online.
+    // A status transition changes the query key and drops the old borrowed API.
+    queryFn: () => listConfiguredHostAgents(hosts, getPaseoClient),
+    refetchOnWindowFocus: false,
+  });
 
   const [lastSent, setLastSent] = useState<{ at: string; to: string } | null>(null);
   const [sentTick, setSentTick] = useState(0);
   const send = useMutation({
-    mutationFn: () =>
-      callSend({
-        daemon: target?.counterparty.daemonServerId ?? target?.counterparty.daemon ?? "",
-        agentId: target?.counterparty.agentId ?? "",
+    mutationFn: async () => {
+      if (!target) throw new Error("Choose a target before sending.");
+      if (target.configuredHostServerId) {
+        // Acquire immediately before send. A configured host can disconnect or
+        // release an earlier borrowed API while this surface remains mounted.
+        const stamped = `${buildXCommsEnvelope({
+          sender: { agentId, agentName: "User", host: "paseo-client", daemonServerId: null, cwd: null },
+          target: { daemon: target.configuredHostServerId, agentId: target.counterparty.agentId },
+          sentAt: new Date().toISOString(),
+        })}\n\n${draft}`;
+        await sendConfiguredHostAgent({
+          serverId: target.configuredHostServerId,
+          agentId: target.counterparty.agentId ?? "",
+          message: stamped,
+          getClient: getPaseoClient,
+        });
+        return { ok: true, error: null };
+      }
+      // Existing registry/MCP relay and direct-peer route stays exactly here.
+      return callSend({
+        daemon: target.counterparty.daemonServerId ?? target.counterparty.daemon ?? "",
+        agentId: target.counterparty.agentId ?? "",
         prompt: draft,
         fromAgentId: agentId,
         fromAgentName: "User",
-      }),
+      });
+    },
     onSuccess: (data) => {
       if (data.ok && target) {
         const now = new Date().toISOString();
@@ -187,7 +224,7 @@ export function CrossDaemonConversation({
     draftCache.set(agentId, v);
     setDraft(v);
   }, [agentId]);
-  const setTargetCached = useCallback((c: ConversationPartner | null) => {
+  const setTargetCached = useCallback((c: SelectedTarget | null) => {
     targetCache.set(agentId, c);
     setTarget(c);
   }, [agentId]);
@@ -206,6 +243,22 @@ export function CrossDaemonConversation({
     });
     setPickerOpen(false);
   }, [setTargetCached, serverIdByName]);
+  const pickConfiguredHostAgent = useCallback((host: { serverId: string }, selectedAgent: { agentId: string; name: string }) => {
+    const counterparty = {
+      daemon: host.serverId,
+      daemonServerId: host.serverId,
+      agentId: selectedAgent.agentId,
+      agentName: selectedAgent.name,
+    };
+    setTargetCached({
+      conversationId: threadKeyForCounterparty(counterparty),
+      counterparty,
+      lastActivity: new Date().toISOString(),
+      messageCount: 0,
+      configuredHostServerId: host.serverId,
+    });
+    setPickerOpen(false);
+  }, [setTargetCached]);
 
   return (
     <View style={{ padding: 12, flex: 1 }}>
@@ -414,6 +467,39 @@ export function CrossDaemonConversation({
       ) : null}
       <Modal title="New conversation" open={pickerOpen} onOpenChange={setPickerOpen}>
         <ModalContent>
+          <View>
+            <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12, fontWeight: "700" as const, marginTop: 4, textTransform: "uppercase" as const }}>
+              Configured hosts
+            </Text>
+            {hosts.map((host) => {
+              const hostAgents = configuredHosts.data?.find((entry) => entry.host.serverId === host.serverId);
+              const unavailable = host.status !== "online";
+              return (
+                <View key={host.serverId}>
+                  <Text style={{ color: unavailable ? theme.colors.foregroundMuted : theme.colors.accent, fontSize: 12, fontWeight: "700" as const, marginTop: 10 }}>
+                    {host.label} ({host.serverId}) · {host.status}{unavailable ? " (unavailable)" : ""}
+                  </Text>
+                  {host.status === "online" && configuredHosts.isPending ? (
+                    <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12, paddingLeft: 10 }}>Loading agents…</Text>
+                  ) : null}
+                  {hostAgents?.error ? (
+                    <Text style={{ color: theme.colors.statusDanger, fontSize: 12, paddingLeft: 10 }}>Unavailable: {hostAgents.error}</Text>
+                  ) : null}
+                  {hostAgents?.agents.map((configuredAgent) => (
+                    <Pressable
+                      key={`${configuredAgent.serverId}/${configuredAgent.agentId}`}
+                      onPress={() => pickConfiguredHostAgent(host, configuredAgent)}
+                      style={({ pressed }) => [{ flexDirection: "row", alignItems: "center", paddingVertical: 6, paddingLeft: 10 }, pressed && { opacity: 0.7 }]}
+                    >
+                      <Text style={{ color: theme.colors.foreground, fontSize: 13, flexShrink: 1 }}>
+                        {configuredAgent.name} ({configuredAgent.agentId}){configuredAgent.status ? ` · ${configuredAgent.status}` : ""}
+                      </Text>
+                    </Pressable>
+                  ))}
+                </View>
+              );
+            })}
+          </View>
           {introspect.isPending ? <Text style={{ color: theme.colors.foregroundMuted, fontSize: 13 }}>Loading agents…</Text> : null}
           {introspect.error ? <Text style={{ color: theme.colors.statusDanger, fontSize: 12 }}>{String(introspect.error)}</Text> : null}
           <View>

package/client/x-comms-pill.tsx

@@ -15,7 +15,7 @@ import {
   type ComposerPillRegistrar,
   type RenderModalProps,
   type RenderPillProps,
-} from "paseo-plugin-helper/client";
+} from "./vendor/paseo-plugin-helper/index";
 import { useEffect, useMemo, useState } from "react";
 import { Text } from "react-native";
 import { CrossDaemonConversation } from "./x-comms-conversation";

package/client/x-comms-tool-call.tsx

@@ -1,6 +1,6 @@
 import { type PluginTimelineItemProps, type PluginTimelineTransformerContribution, type PluginTimelineRendererContribution } from "@getpaseo/plugin/client";
 import { Icon } from "@getpaseo/plugin/client/react-native";
-import { Badge, Card, CodeBlock, StatusDot } from "paseo-plugin-helper/client";
+import { Badge, Card, CodeBlock, StatusDot } from "./vendor/paseo-plugin-helper/index";
 import { Text, View } from "react-native";
 import { ViaXComms } from "./via-x-comms";
 import { usePeerDisplay } from "./peer-label";

package/index.client.tsx

@@ -0,0 +1,78 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { useRpc } from "@getpaseo/plugin/client";
+import { Icon, Modal, useToast, ScrollView, FlatList, TextInput as HostTextInput, copyText } from "@getpaseo/plugin/client/react-native";
+import { initClientHelpers, registerSidebarSurface, type ComposerPillRegistrar } from "./client/vendor/paseo-plugin-helper/index";
+import { MainSurface } from "./client/main";
+import { crossDaemonTransformer, crossDaemonRenderer, outboxNoticeRenderer } from "./client/x-comms-timeline";
+import { crossDaemonToolCallTransformer, crossDaemonToolCallRenderer } from "./client/x-comms-tool-call";
+import { contributeClient } from "./client/x-comms-pill";
+import { CrossDaemonPanel } from "./client/x-comms-panel";
+
+initClientHelpers({ Icon, Modal, useRpc, useToast, copyText, ScrollView, FlatList, TextInput: HostTextInput });
+
+export default function contribute(client: PluginClientContext) {
+  client.addTimelineTransformer(crossDaemonTransformer);
+  client.addTimelineRenderer(crossDaemonRenderer);
+  client.addTimelineRenderer(outboxNoticeRenderer);
+  client.addTimelineTransformer(crossDaemonToolCallTransformer);
+  client.addTimelineRenderer(crossDaemonToolCallRenderer);
+  client.addWorkspacePanel({
+    id: "x-comms",
+    title: "X-comms",
+    icon: "PhoneOutgoing",
+    context: "agent",
+    Component: CrossDaemonPanel,
+  });
+  // registerSidebarSurface injects <PluginThemeProvider> so the surface's
+  // helper primitives resolve the host theme/layout (compact + mobile).
+  registerSidebarSurface(client, {
+    id: "main",
+    title: "X-comms",
+    icon: "PhoneOutgoing",
+    Component: MainSurface,
+  });
+  const headerButtons = new Map<string, () => void>();
+  const addHeaderButtonForWorkspace = (workspaceId: string) => {
+    if (!workspaceId || headerButtons.has(workspaceId)) return;
+    const registration = client.addHeaderButton({
+      id: "x-comms",
+      workspaceId,
+      button: {
+        title: "X-comms",
+        icon: "PhoneOutgoing",
+        behavior: { kind: "action", onPress: () => client.openSurface("main") },
+      },
+    });
+    headerButtons.set(workspaceId, () => registration.remove());
+  };
+  const unsubscribeAgents = client.paseo.agents.subscribe((update) => {
+    if (update.kind !== "upsert" || !update.agent.workspaceId) return;
+    addHeaderButtonForWorkspace(update.agent.workspaceId);
+  });
+  // Register buttons for agents already present: subscribe only fires on
+  // future upserts, so without this the icon is missing after a Paseo
+  // restart until the next agent event.
+  void Promise.resolve()
+    .then(() => client.paseo.agents.list())
+    .then(
+      (res) => {
+        const entries = Array.isArray(
+          (res as unknown as { entries?: unknown }).entries,
+        )
+          ? (res as unknown as { entries: Array<{ agent?: { workspaceId?: unknown } }> }).entries
+          : [];
+        for (const { agent } of entries) {
+          if (typeof agent?.workspaceId === "string") addHeaderButtonForWorkspace(agent.workspaceId);
+        }
+      },
+      (err) => console.warn("[x-comms] Failed to list agents for header buttons:", err),
+    );
+  // Paseo 0.8 client is button-only; registerComposerPill probes the host shape at runtime.
+  const disposePill = contributeClient(client as unknown as ComposerPillRegistrar);
+  return () => {
+    unsubscribeAgents();
+    for (const remove of headerButtons.values()) remove();
+    headerButtons.clear();
+    disposePill();
+  };
+}

package/index.server.ts

@@ -0,0 +1,84 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import {
+  handleRegistryRead,
+  handleDaemonAdd,
+  handleDaemonUpdate,
+  handleDaemonRemove,
+  handleDaemonHealth,
+  handleServerStatus,
+  handleConversationSend,
+  handleIntrospectAgents,
+  handleIntroduceAgents,
+  handleDaemonProbe,
+  handleUiPrefsGet,
+  handleUiPrefsSet,
+  handleSnapshotRefresh,
+  handleDaemonDump,
+  handleIdentitySync,
+  handlePresenceAnnounce,
+  handlePresenceRetract,
+  handlePresenceList,
+  injectionEnabled,
+  onLocalAgentCreated,
+  onLocalAgentArchived,
+  rememberPaseo,
+  stopOutboxWorker,
+} from "./server/handlers";
+import { maybeRegisterInjection, toInjectionServer } from "./server/injection";
+import { handlePeerStatus } from "./server/peer-status";
+import {
+  registryReadRpc,
+  daemonAddRpc,
+  daemonUpdateRpc,
+  daemonRemoveRpc,
+  daemonHealthRpc,
+  serverStatusRpc,
+  conversationSendRpc,
+  introspectAgentsRpc,
+  introduceAgentsRpc,
+  daemonProbeRpc,
+  uiPrefsGetRpc,
+  uiPrefsSetRpc,
+  snapshotRefreshRpc,
+  daemonDumpRpc,
+  identitySyncRpc,
+  presenceAnnounceRpc,
+  presenceRetractRpc,
+  presenceListRpc,
+  peerStatusRpc,
+} from "./shared/registry";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(registryReadRpc, handleRegistryRead);
+  server.handle(daemonAddRpc, handleDaemonAdd);
+  server.handle(daemonUpdateRpc, handleDaemonUpdate);
+  server.handle(daemonRemoveRpc, handleDaemonRemove);
+  server.handle(daemonHealthRpc, handleDaemonHealth);
+  server.handle(serverStatusRpc, handleServerStatus);
+  server.handle(conversationSendRpc, handleConversationSend);
+  server.handle(introspectAgentsRpc, handleIntrospectAgents);
+  server.handle(introduceAgentsRpc, handleIntroduceAgents);
+  server.handle(daemonProbeRpc, handleDaemonProbe);
+  server.handle(uiPrefsGetRpc, handleUiPrefsGet);
+  server.handle(uiPrefsSetRpc, handleUiPrefsSet);
+  server.handle(snapshotRefreshRpc, handleSnapshotRefresh);
+  server.handle(daemonDumpRpc, handleDaemonDump);
+  server.handle(identitySyncRpc, handleIdentitySync);
+  server.handle(presenceAnnounceRpc, handlePresenceAnnounce);
+  server.handle(presenceRetractRpc, handlePresenceRetract);
+  server.handle(presenceListRpc, handlePresenceList);
+  server.handle(peerStatusRpc, handlePeerStatus);
+  server.on("agent.created", ({ agent }, context) => {
+    rememberPaseo(context.paseo);
+    void onLocalAgentCreated(agent).catch(() => {});
+  });
+  server.on("agent.archived", ({ agent }, context) => {
+    rememberPaseo(context.paseo);
+    void onLocalAgentArchived(agent).catch(() => {});
+  });
+  const removeInjection = maybeRegisterInjection(toInjectionServer(server), { enabled: injectionEnabled() });
+  return () => {
+    stopOutboxWorker();
+    removeInjection();
+  };
+}

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@xpufx/paseo-x-comms",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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,
+  "engines": {
+    "node": ">=18"
+  },
   "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"
+    "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/configured-hosts.test.ts client/conversation-threads.test.ts client/attribution.test.ts client/message-direction.test.ts"
   },
   "keywords": [
     "paseo",
@@ -25,17 +28,17 @@
   "license": "MIT",
   "dependencies": {
     "@getpaseo/client": "0.9.0-beta.2",
+    "@getpaseo/plugin": "0.9.0-beta.2",
     "@getpaseo/protocol": "0.9.0-beta.2",
-    "@modelcontextprotocol/sdk": "^1.30.0"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
   },
   "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"
+    "typescript": "^5.9.3"
   },
   "repository": {
     "type": "git",
@@ -45,6 +48,8 @@
     "paseo-plugin.json",
     "README.md",
     "LICENSE",
+    "index.client.tsx",
+    "index.server.ts",
     "client",
     "server",
     "shared",

package/paseo-plugin.json

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

package/server/conversations-snapshot.ts

@@ -1,4 +1,4 @@
-import { PluginStorage } from "paseo-plugin-helper/server";
+import { PluginStorage } from "./vendor/paseo-plugin-helper/index";
 import {
   emptyConversationsSnapshot,
   type XCommsConversationsSnapshot,

package/server/handlers.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createPeriodicTask, createPluginLogger, safeSpawn } from "paseo-plugin-helper/server";
+import { createPeriodicTask, createPluginLogger, safeSpawn } from "./vendor/paseo-plugin-helper/index";
 import type { PaseoApi } from "@getpaseo/client";
-import { withTimeout } from "paseo-plugin-helper/shared";
+import { withTimeout } from "../shared/vendor/paseo-plugin-helper/async";
 import { getSnapshotFresh, agentCountFor, refreshSnapshot, initializeSnapshot } from "./snapshot";
 import {
   registryReadRpc,
@@ -397,7 +397,7 @@ export async function handleDaemonProbe(input: { value: string }) {
 
 
 
-import { PluginStorage } from "paseo-plugin-helper/server";
+import { PluginStorage } from "./vendor/paseo-plugin-helper/index";
 import { resolveFeatureFlags, resolveInjectionEnabled, resolveOutboxExpiryMs, resolvePresenceEnabled, applyFeaturePrefsUpdate } from "./settings.ts";
 import {
   OUTBOX_POLL_INTERVAL_MS,

package/server/injection.ts

@@ -7,7 +7,7 @@ import {
   type McpInjectionHookHandler,
   type McpInjectionServer,
   type McpStdioInjectionConfig,
-} from "paseo-plugin-helper/server";
+} from "./vendor/paseo-plugin-helper/index";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { serverPath } from "./server-status.ts";
 import { stateDir } from "./registry.ts";

package/server/mcp-client.ts

@@ -1,5 +1,5 @@
-import { McpClient } from "paseo-plugin-helper/mcp";
-import { createPluginLogger } from "paseo-plugin-helper/server";
+import { McpClient } from "./vendor/paseo-plugin-helper/mcp/index";
+import { createPluginLogger } from "./vendor/paseo-plugin-helper/index";
 
 const log = createPluginLogger("paseo-x-comms", { subsystem: "mcp-client" });
 

package/server/outbox.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { PluginStorage } from "paseo-plugin-helper/server";
+import { PluginStorage } from "./vendor/paseo-plugin-helper/index";
 
 /**
  * Outbox for outbound conversation messages that could not be delivered.

package/server/peer-channel.ts

@@ -4,8 +4,8 @@ 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";
+import { createPluginLogger, safeSpawn } from "./vendor/paseo-plugin-helper/index";
+import { withTimeout } from "../shared/vendor/paseo-plugin-helper/async";
 
 const log = createPluginLogger("paseo-x-comms", { subsystem: "peer-channel" });
 const CONNECT_TIMEOUT_MS = 8000;

package/server/peer-status.ts

@@ -1,7 +1,7 @@
 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 { createPluginLogger } from "./vendor/paseo-plugin-helper/index";
+import { withTimeout } from "../shared/vendor/paseo-plugin-helper/async";
 import { currentRegistryPath, readRegistry } from "./registry";
 import { resolvePeerTarget } from "./peer-channel";
 

package/server/presence.ts

@@ -1,4 +1,4 @@
-import { PluginStorage } from "paseo-plugin-helper/server";
+import { PluginStorage } from "./vendor/paseo-plugin-helper/index";
 
 /**
  * Presence store (mesh Layer 1, control plane only).

package/server/snapshot.ts

@@ -1,6 +1,6 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { createPluginLogger, safeSpawn } from "paseo-plugin-helper/server";
+import { createPluginLogger, safeSpawn } from "./vendor/paseo-plugin-helper/index";
 import { currentRegistryPath, readRegistry, stateDir, migrateFromRoot } from "./registry";
 
 const snapLog = createPluginLogger("paseo-x-comms", { subsystem: "snapshot" });
@@ -173,4 +173,4 @@ export function agentCountFor(entry: DaemonSnapshotEntry): number {
     (total, project) => total + project.workspaces.reduce((sub, ws) => sub + ws.agents.length, 0),
     0,
   );
-}
+}

package/shared/envelope.ts

@@ -32,6 +32,34 @@ export type CrossDaemonEnvelope = z.infer<typeof EnvelopeSchema>;
 
 export type MessageDirection = "incoming" | "outgoing";
 
+/**
+ * Produce the version-4 wire prefix shared by every x-comms delivery route.
+ * Keeping this browser-safe lets an interactive client send retain the same
+ * attribution contract as the server and MCP routes.
+ */
+export function buildXCommsEnvelope(args: {
+  sender: {
+    agentId: string | null;
+    agentName: string | null;
+    host: string;
+    daemonServerId: string | null;
+    cwd: string | null;
+  };
+  target: { daemon: string | null; agentId: string | null };
+  sentAt: string;
+}): string {
+  return `${META_PREFIX}${JSON.stringify({
+    xComms: {
+      version: 4,
+      type: "x-comms.message",
+      direction: "outgoing",
+      sender: args.sender,
+      target: args.target,
+      sentAt: args.sentAt,
+    },
+  })}`;
+}
+
 /**
  * Viewer-relative direction. The wire envelope stamps direction "outgoing"
  * from the sender's side, so only a message from self counts as user-sent.

package/shared/registry.ts

@@ -1,4 +1,4 @@
-import { defineRpc } from "paseo-plugin-helper/shared";
+import { defineRpc } from "./vendor/paseo-plugin-helper/rpc";
 import { z } from "zod";
 
 const DaemonEntrySchema = z.object({