@xpufx/paseo-x-comms 0.3.0

package/client/x-comms-pill.tsx

@@ -0,0 +1,193 @@
+import { useRpc } from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import {
+  AboutSection,
+  ActionBar,
+  Card,
+  EmptyState,
+  FormRow,
+  ModalBody,
+  StatusDot,
+  Tabs,
+  Toggle,
+  registerComposerPill,
+  usePluginTheme,
+  type ComposerPillRegistrar,
+  type RenderModalProps,
+  type RenderPillProps,
+} from "paseo-plugin-helper/client";
+import { useEffect, useMemo, useState } from "react";
+import { Text } from "react-native";
+import { CrossDaemonConversation } from "./x-comms-conversation";
+import { uiPrefsGetRpc, uiPrefsSetRpc } from "../shared/registry";
+
+// Keep the modal a readable centered column instead of stretching edge-to-edge
+// on large viewports. The cap lives in the helper (`ModalBody
+// maxContentWidth`); this is the only place the pill picks the value.
+const X_COMMS_CONTENT_MAX_WIDTH = 600;
+
+// Raw Text is retained only for the composer pill label and the muted
+// reload-needed caption. Every tab, layout, settings row, toggle, status and
+// empty state goes through a paseo-plugin-helper primitive.
+function CrossDaemonPill(props: RenderPillProps) {
+  const { theme } = props;
+  const style = useMemo(
+    () => ({ color: theme.colors.accent, flexShrink: 1, fontSize: 10 }),
+    [theme],
+  );
+  return (
+    <>
+      <Icon name="PhoneOutgoing" size={9} color={theme.colors.accent} />
+      <Text numberOfLines={1} style={style}>
+        X-comms
+      </Text>
+    </>
+  );
+}
+
+function XCommsSettings() {
+  const callGet = useRpc(uiPrefsGetRpc);
+  const callSet = useRpc(uiPrefsSetRpc);
+  const { colors } = usePluginTheme();
+  const [presence, setPresence] = useState<boolean | null>(null);
+  const [injection, setInjection] = useState<boolean | null>(null);
+  const [collapsed, setCollapsed] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    let live = true;
+    callGet({})
+      .then((prefs) => {
+        if (!live) return;
+        setPresence(prefs.presenceEnabled);
+        setInjection(prefs.injectionEnabled);
+        setCollapsed(prefs.prereqsCollapsed);
+      })
+      .catch((cause: unknown) => {
+        if (live) setError(cause instanceof Error ? cause.message : String(cause));
+      });
+    return () => {
+      live = false;
+    };
+  }, [callGet]);
+  const save = (next: { presenceEnabled: boolean; injectionEnabled: boolean }) => {
+    setSaving(true);
+    setError(null);
+    callSet({ prereqsCollapsed: collapsed, ...next })
+      .then((prefs) => {
+        setPresence(prefs.presenceEnabled);
+        setInjection(prefs.injectionEnabled);
+      })
+      .catch((cause: unknown) => setError(cause instanceof Error ? cause.message : String(cause)))
+      .finally(() => setSaving(false));
+  };
+  const loading = presence === null || injection === null;
+  return (
+    <>
+      {loading ? (
+        error ? (
+          <EmptyState icon="AlertTriangle" title="Couldn't load settings" description={error} />
+        ) : (
+          <EmptyState icon="Sliders" title="Loading settings…" />
+        )
+      ) : (
+        <Card>
+          <Card.Header title="Preferences" />
+          <FormRow
+            label="Presence"
+            description="Announce local agent births and retracts to paired daemons."
+          >
+            <Toggle
+              value={presence}
+              onValueChange={(next) => {
+                setPresence(next);
+                save({ presenceEnabled: next, injectionEnabled: injection });
+              }}
+              disabled={saving}
+            />
+          </FormRow>
+          <FormRow
+            label="MCP injection"
+            description="Add the x-comms server to every newborn agent."
+          >
+            <Toggle
+              value={injection}
+              onValueChange={(next) => {
+                setInjection(next);
+                save({ presenceEnabled: presence, injectionEnabled: next });
+              }}
+              disabled={saving}
+            />
+          </FormRow>
+          <Text style={{ color: colors.foregroundMuted, fontSize: 11 }}>
+            Changes take effect after the plugin reloads.
+          </Text>
+        </Card>
+      )}
+      {!loading && (saving || error) ? (
+        <ActionBar align="flex-start">
+          <StatusDot variant={error ? "danger" : "warning"} pulse={!error} />
+          <Text
+            selectable
+            style={{
+              color: error ? colors.statusDanger : colors.foregroundMuted,
+              fontSize: 12,
+              flexShrink: 1,
+            }}
+          >
+            {error ?? "Saving…"}
+          </Text>
+        </ActionBar>
+      ) : null}
+    </>
+  );
+}
+
+const X_COMMS_TABS = [
+  { id: "chat", label: "Chat" },
+  { id: "settings", label: "Settings" },
+  { id: "about", label: "About" },
+];
+
+function XCommsModalContent({ theme, agentId }: { theme: RenderModalProps["theme"]; agentId: string }) {
+  const [tab, setTab] = useState("chat");
+  return (
+    <ModalBody
+      header={<Tabs tabs={X_COMMS_TABS} activeTab={tab} onTabChange={setTab} />}
+      headerMode="pinned"
+      maxContentWidth={X_COMMS_CONTENT_MAX_WIDTH}
+      headerStyle={{ paddingHorizontal: 12, paddingTop: 12, paddingBottom: 6 }}
+    >
+      {tab === "about" ? (
+        <AboutSection
+          name="X-comms"
+          description="Cross-daemon agent conversation over Paseo Relay."
+          version="0.3.0"
+          repository="https://github.com/xpufx/paseo-x-comms"
+          license="MIT"
+          density="tiny"
+        />
+      ) : tab === "settings" ? (
+        <XCommsSettings />
+      ) : (
+        <CrossDaemonConversation theme={theme} agentId={agentId} />
+      )}
+    </ModalBody>
+  );
+}
+
+/**
+ * One composer pill per agent. Lifecycle (agent subscription, pill mount and
+ * unmount, modal open state, theme) is managed by registerComposerPill; this
+ * module only supplies the pill body and modal content.
+ */
+export function contributeClient(client: ComposerPillRegistrar) {
+  return registerComposerPill(client, {
+    id: "x-comms",
+    title: "X-comms",
+    icon: "PhoneOutgoing",
+    modalTitle: "X-comms",
+    renderPill: (props) => <CrossDaemonPill {...props} />,
+    renderModal: (props) => <XCommsModalContent theme={props.theme} agentId={props.agentId} />,
+  });
+}

package/client/x-comms-timeline.tsx

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { type PluginTimelineItemProps, type PluginTimelineTransformerContribution, type PluginTimelineRendererContribution } from "@getpaseo/plugin/client";
+import type { PluginTheme } from "@getpaseo/plugin";
+import { Icon, copyText, useToast } from "@getpaseo/plugin/client/react-native";
+import { useCallback, useMemo, useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import { EnvelopeSchema, cardSignal, isOverflowing, parseEnvelope, type CrossDaemonEnvelope } from "../shared/envelope";
+import {
+  OUTBOX_NOTICE_KIND,
+  OUTBOX_NOTICE_VERSION,
+  OutboxNoticeSchema,
+  type OutboxNotice,
+} from "../shared/outbox";
+import { formatPeerDisplay, usePeerAlias } from "./peer-label";
+import { ViaXComms } from "./via-x-comms";
+
+export { parseEnvelope, type CrossDaemonEnvelope };
+
+const ItemSchema = z.object({
+  envelope: EnvelopeSchema,
+  body: z.string(),
+});
+
+function senderLabel(env: CrossDaemonEnvelope, alias: string | null): string {
+  const s = env.xComms.sender;
+  const name = s.agentName ?? s.agentId ?? "unknown agent";
+  return `${name} @ ${formatPeerDisplay(alias, s.daemonServerId)}`;
+}
+
+function MessageBody({ theme, body }: { theme: PluginTheme; body: string }) {
+  const toast = useToast();
+  const [expanded, setExpanded] = useState(false);
+  const [overflows, setOverflows] = useState(false);
+  const onTextLayout = useCallback(
+    (e: { nativeEvent: { lines: unknown[] } }) => {
+      const next = isOverflowing(e.nativeEvent.lines.length);
+      setOverflows((prev) => (prev === next ? prev : next));
+    },
+    [],
+  );
+  const copy = useCallback(() => {
+    copyText(body).then(
+      () => toast.show("Copied", { variant: "success" }),
+      () => toast.error("Copy failed"),
+    );
+  }, [body, toast]);
+  if (!expanded) {
+    return (
+      <View>
+        <Text
+          style={{ color: theme.colors.foreground, fontSize: 13 }}
+          numberOfLines={3}
+          ellipsizeMode="tail"
+          onTextLayout={onTextLayout}
+        >
+          {body}
+        </Text>
+        {overflows ? (
+          <Pressable accessibilityRole="button" onPress={() => setExpanded(true)} hitSlop={8}>
+            <Text style={{ color: theme.colors.accent, fontSize: 12, marginTop: 2 }}>Show more</Text>
+          </Pressable>
+        ) : null}
+      </View>
+    );
+  }
+  return (
+    <View
+      style={{
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        borderRadius: 6,
+        padding: 8,
+        marginTop: 2,
+        flexDirection: "row",
+      }}
+    >
+      <Text style={{ color: theme.colors.foreground, fontSize: 13, flexShrink: 1, flexGrow: 1 }} selectable>
+        {body}
+      </Text>
+      <View style={{ flexDirection: "column", gap: 8, marginLeft: 8 }}>
+        <Pressable accessibilityRole="button" accessibilityLabel="Copy message" onPress={copy} hitSlop={10}>
+          <Text style={{ color: theme.colors.accent, fontSize: 14 }}>⧉</Text>
+        </Pressable>
+        <Pressable accessibilityRole="button" onPress={() => setExpanded(false)} hitSlop={8}>
+          <Text style={{ color: theme.colors.accent, fontSize: 12 }}>Less</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+function CrossDaemonMessage({ theme, agentId, item }: PluginTimelineItemProps<z.infer<typeof ItemSchema>>) {
+  const alias = usePeerAlias(item.data.envelope.xComms.sender.daemonServerId);
+  const label = useMemo(
+    () => senderLabel(item.data.envelope, alias),
+    [item.data.envelope, alias],
+  );
+  const { direction, userSent } = cardSignal(item.data.envelope, agentId);
+  const incoming = direction === "incoming";
+  const signalColor = userSent ? theme.colors.statusDanger : theme.colors.foregroundMuted;
+  return (
+    <View style={{ paddingVertical: 4 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 6, marginBottom: 2 }}>
+        <Icon
+          name={incoming ? "PhoneIncoming" : "PhoneOutgoing"}
+          size={14}
+          color={signalColor}
+        />
+        <Text style={{ color: signalColor, fontSize: 12, fontWeight: "600" as const }}>
+          x-comms · {incoming ? "Incoming" : "Outgoing"} · {label}
+        </Text>
+      </View>
+      {item.data.body.length > 0 ? (
+        <MessageBody theme={theme} body={item.data.body} />
+      ) : null}
+      <ViaXComms theme={theme} />
+    </View>
+  );
+}
+
+/**
+ * Timeline transformer: paseo calls this for every user_message. If the text
+ * carries our meta envelope, we emit a plugin-typed item our renderer draws
+ * distinctly. The envelope is the only discriminator.
+ */
+export const crossDaemonTransformer: PluginTimelineTransformerContribution<"user_message"> = {
+  id: "x-comms-message",
+  query: { itemType: "user_message" },
+  transform({ item }) {
+    const parsed = parseEnvelope(item.text);
+    if (!parsed) return undefined;
+    return {
+      items: [
+        {
+          type: "plugin",
+          kind: "x-comms-message",
+          version: 1,
+          data: { envelope: parsed.envelope, body: parsed.body },
+        },
+      ],
+    };
+  },
+};
+
+export const crossDaemonRenderer: PluginTimelineRendererContribution<typeof ItemSchema> = {
+  kind: "x-comms-message",
+  version: 1,
+  schema: ItemSchema,
+  Component: CrossDaemonMessage,
+};
+
+/**
+ * Expiry notice for a message the outbox gave up on. Local to the sender's
+ * timeline; never part of the wire envelope.
+ */
+function OutboxNoticeCard({ theme, item }: PluginTimelineItemProps<OutboxNotice>) {
+  return (
+    <View style={{ paddingVertical: 4 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 6, marginBottom: 2 }}>
+        <Icon name="AlertTriangle" size={14} color={theme.colors.statusWarning} />
+        <Text style={{ color: theme.colors.statusWarning, fontSize: 12, fontWeight: "600" as const }}>
+          x-comms · Delivery failed
+        </Text>
+      </View>
+      <Text style={{ color: theme.colors.foreground, fontSize: 13 }}>{item.data.reason}</Text>
+      <ViaXComms theme={theme} />
+    </View>
+  );
+}
+
+export const outboxNoticeRenderer: PluginTimelineRendererContribution<typeof OutboxNoticeSchema> = {
+  kind: OUTBOX_NOTICE_KIND,
+  version: OUTBOX_NOTICE_VERSION,
+  schema: OutboxNoticeSchema,
+  Component: OutboxNoticeCard,
+};

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

@@ -0,0 +1,85 @@
+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 { Text, View } from "react-native";
+import { ViaXComms } from "./via-x-comms";
+import { usePeerDisplay } from "./peer-label";
+import { ToolCallCardSchema, summarizeToolCall, type ToolCallCardData } from "./tool-call";
+
+function statusVariant(status: string): "success" | "warning" | "danger" | "info" {
+  if (status === "completed") return "success";
+  if (status === "running") return "info";
+  if (status === "failed" || status === "canceled") return "danger";
+  return "warning";
+}
+
+function ToolCallCard({ theme, item }: PluginTimelineItemProps<ToolCallCardData>) {
+  const data = item.data;
+  const peer = usePeerDisplay(data.targetServerId, data.targetAlias);
+  const title = data.agentId ? `${data.tool} · ${data.agentId.slice(0, 8)}` : data.tool;
+  return (
+    <Card>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 6, marginBottom: 4 }}>
+        <Icon name="PhoneOutgoing" size={13} color={theme.colors.accent} />
+        <Text style={{ color: theme.colors.foreground, fontSize: 12, fontWeight: "600" as const, flexShrink: 1 }}>
+          {title}
+        </Text>
+        <StatusDot variant={statusVariant(data.status)} size="sm" />
+        <Badge label={data.status} variant={statusVariant(data.status)} />
+      </View>
+      {(data.targetAlias || data.targetServerId) ? (
+        <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12, marginBottom: 4 }} selectable>
+          {peer}
+        </Text>
+      ) : null}
+      {data.output ? (
+        <CodeBlock code={data.output} language="json" copyable maxHeight={220} />
+      ) : null}
+      <ViaXComms theme={theme} />
+    </Card>
+  );
+}
+
+/**
+ * Timeline transformer: matches tool_call items for x_comms_* tools and
+ * replaces the raw JSON row with a card. Matching is a pure name-prefix
+ * check with no visibility toggles: tool calls never render as JSON walls.
+ */
+export const crossDaemonToolCallTransformer: PluginTimelineTransformerContribution<"tool_call"> = {
+  id: "x-comms-tool-call",
+  query: { itemType: "tool_call" },
+  transform({ item }) {
+    const summary = summarizeToolCall({
+      name: item.name,
+      status: item.status,
+      error: item.status === "failed" ? item.error : undefined,
+      detail: item.detail,
+    });
+    if (!summary) return undefined;
+    return {
+      items: [
+        {
+          type: "plugin",
+          kind: "x-comms-tool-call",
+          version: 1,
+          data: {
+            tool: summary.tool,
+            agentId: summary.agentId,
+            targetAlias: summary.targetAlias,
+            targetServerId: summary.targetServerId,
+            status: summary.status,
+            failed: summary.failed,
+            output: summary.output,
+          },
+        },
+      ],
+    };
+  },
+};
+
+export const crossDaemonToolCallRenderer: PluginTimelineRendererContribution<typeof ToolCallCardSchema> = {
+  kind: "x-comms-tool-call",
+  version: 1,
+  schema: ToolCallCardSchema,
+  Component: ToolCallCard,
+};

package/docs/mesh.md

@@ -0,0 +1,115 @@
+# Daemon Mesh: Presence, Injection, and Visibility
+
+How Paseo daemons find each other, how agents get tools without being asked,
+and how the fleet stays observable. Three mechanisms, each independent,
+composable in that order.
+
+This mirrors `docs/mesh.md` in `paseo-plugin-helper` (0.8 line): both repos
+tell the same story and share one vocabulary (announce/retract, tombstones,
+intended vs actual). The helper doc is the vision; this file records what
+x-comms implements and what is still ahead.
+
+## Thesis
+
+Presence RPCs plus link-identity is the foundation; reliable agent messaging
+rides on top of it. Conversation (`x_comms_send` and friends) is the top
+layer. Nothing below it ever speaks in chat messages.
+
+## Layer 0: Link identity
+
+Every peer link is authenticated. Sender identity (serverId) comes from the
+link itself, never from message payloads.
+
+What x-comms does today:
+- Outbound: after `DaemonClient.connect()`, the handshake identity from
+  `getLastServerInfoMessage()` is checked against the expected serverId
+  embedded in the registry relay offer. A mismatch aborts before any
+  payload is sent (`server/peer-channel.ts`).
+- Inbound: RPC handlers have no link context, so the receiver accepts only
+  entries whose serverId matches an explicitly paired peer (seed links
+  stay explicit). Anything else is dropped and counted as rejected.
+- Own identity is read locally (`~/.paseo/server-id`, falling back to a
+  local `paseo daemon status` probe), never from agent config or payloads.
+
+Known gap: true receiver-side link verification needs daemon support; the
+known-peer check is the approximation until then.
+
+## Layer 1: Presence (control plane, invisible)
+
+- `presence.announce` (birth batch) and `presence.retract`, keyed by
+  `(serverId, agentId)`, carried as plugin RPCs over the authenticated
+  peer channel (`server/peer-channel.ts` via `DaemonClient.invokePluginRpc`).
+  Never through conversation sends.
+- Local hooks only: `on("agent.created")` buffers and announces,
+  `on("agent.archived")` retracts immediately (`index.server.ts`).
+- Store (`server/presence.ts`, `PluginStorage` pattern, `presence.json`):
+  live entries, sticky tombstones, bounded seen-id LRU (1000), queued
+  retracts per peer with retry piggybacked on the next outbound pass.
+- Anti-loop rules, in order of importance:
+  1. Seen-id LRU drops duplicates.
+  2. Never forward gossip: only locally-originated events leave the daemon
+     (origin tracking plus the transport edge only sends local entries).
+  3. Retract-before-reannounce with sticky tombstones (kept 2x the live
+     TTL) so delayed births cannot resurrect the dead.
+  4. TTL (7 days live) purely as a safety net; firing logs an alert.
+- Explicitly deferred: vector clocks, anti-entropy sync, Merkle anything.
+- Birth payload is minimal: `(serverId, agentId, name, provider,
+  timestamp)`. No cwd, workspace, or project.
+- Debug surface: `presence.list` RPC (live, tombstones, pending count).
+  No UI.
+- Scope flag: daemon-wide `presenceEnabled` in plugin settings (on by
+  default). It gates local capture and fan-out; inbound processing
+  continues so re-enabling finds warm state.
+- Known limitation: births missed while a peer is offline are not
+  backfilled in this slice. Retracts are queued and retried.
+
+## Layer 2: Injection (tools by default)
+
+Implemented on this branch (`server/injection.ts`, wired in
+`index.server.ts`):
+- `registerMcpInjection` from the helper wraps `server.before`
+  ("agent.create") with merge-preserving, non-mutating semantics.
+- Key scheme `x-comms.<serverId>` (fallback plain `x-comms` with a logged
+  warning if the local server id is unreadable).
+- Stdio config uses `process.execPath` plus the runtime-resolved bundled
+  server path, so it works from git checkouts on foreign hosts.
+- No provider filter (all agents). Daemon-wide `injectionEnabled` toggle
+  in plugin settings, default on; changes apply on plugin reload.
+- Per-agent opt-out deferred. MCP server, envelope, and presence untouched.
+
+## Layer 3: Visibility (intended vs actual)
+
+Not implemented. Planned: injection snapshot plus diff against live
+session configs. Separate slice.
+
+## Layer 4: Conversation reliability (sender-side outbox)
+
+Implemented (`server/outbox.ts` + the plugin server, #12):
+- Failed `conversation.send` calls are held in an `outbox.json` store and
+  retried over the same `x_comms_send` path: exponential backoff
+  (5s doubling to 60s), a 15s periodic sweep, and an immediate retry when a
+  peer's reachability flips false -> true (health/snapshot).
+- Held messages expire after a configurable window (default 10 min); on
+  expiry the sender gets an `x-comms-outbox-notice` timeline item with the
+  reason, then the entry is dropped.
+- Scope: this covers plugin-server sends (panel/composer). Agent-initiated
+  `x_comms_send` calls run in an ephemeral per-session MCP process and are not
+  outboxed.
+- Delivery path (`conversation.send`): a target that resolves to THIS daemon's
+  serverId sends natively through the host `PaseoApi` (`server/local-send.ts`);
+  every remote target goes through the bundled MCP server, which stamps the
+  envelope and shells out to `paseo send --host`. `PaseoApi.send()` is bound to
+  one daemon connection and carries no host/`serverId` (`PaseoAgentSendOptions`
+  has only `messageId`/`images`/`attachments`), so there is no host-targeted SDK
+  call to replace the remote shell-out with. Both producers stamp the identical
+  version-4 envelope, so the wire contract is unchanged.
+- Not implemented: UUID-keyed idempotency. The conversation envelope has no
+  message-id slot and receivers keep no seen-id set for messages, so a retry
+  after an ambiguous failure can re-deliver. Adding it needs a wire-format
+  change (separate decision).
+
+## Trust corollary
+
+Any installed plugin can run these hooks, so peering with a daemon means
+trusting its plugin list. Daemon-wide kill switches (disable the plugin,
+or the `presenceEnabled` flag) must always work instantly.