@xpufx/paseo-x-comms 0.3.0

package/server/injection.ts

@@ -0,0 +1,152 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import {
+  createPluginLogger,
+  registerMcpInjection,
+  type McpInjectionHookHandler,
+  type McpInjectionServer,
+  type McpStdioInjectionConfig,
+} from "paseo-plugin-helper/server";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { serverPath } from "./server-status.ts";
+import { stateDir } from "./registry.ts";
+
+const log = createPluginLogger("paseo-x-comms", { subsystem: "injection" });
+
+/**
+ * Injection key scheme: `x-comms_<serverId>`, namespaced per daemon so key
+ * collisions are impossible by construction and the owning daemon is visible
+ * in agent configs (the visibility layer reads this back). Falls back to
+ * plain `x-comms` only when the local server id is unreadable.
+ *
+ * The separator MUST be `_` (or `-`), never `.`: the name is forwarded to
+ * provider ACP servers, and Gemini's validates it against `^[a-zA-Z0-9_-]+$`.
+ * A dotted name makes `session/new` fail with JSON-RPC -32602 "Invalid params",
+ * which breaks every newborn Antigravity agent (#243).
+ */
+export const INJECTION_KEY_PREFIX = "x-comms_";
+export const INJECTION_FALLBACK_KEY = "x-comms";
+
+export function readLocalServerId(): string | null {
+  try {
+    const id = readFileSync(join(homedir(), ".paseo", "server-id"), "utf8").trim();
+    return id || null;
+  } catch {
+    return null;
+  }
+}
+
+export function injectionServerName(readId: () => string | null = readLocalServerId): string {
+  const id = readId();
+  if (!id) {
+    log.error("injection: local server id unreadable, using fallback key (collision risk if paired daemons do the same)");
+    return INJECTION_FALLBACK_KEY;
+  }
+  return `${INJECTION_KEY_PREFIX}${id}`;
+}
+
+export function injectionServerConfig(): McpStdioInjectionConfig {
+  return {
+    type: "stdio",
+    command: resolveNodeCommand(process.execPath),
+    args: [syncStableServer()],
+  };
+}
+
+/**
+ * Stable install path for the injected server. Plugin checkouts live under
+ * content-addressed directories that are replaced on every update, so any
+ * absolute checkout path baked into a saved agent config rots. The state
+ * dir survives updates, making this path stable across them.
+ */
+export const STABLE_BIN_DIRNAME = "bin";
+export const STABLE_SERVER_FILENAME = "paseo-x-comms.bundled.mjs";
+
+export function stableServerPath(stateDirPath: string = stateDir()): string {
+  return join(stateDirPath, STABLE_BIN_DIRNAME, STABLE_SERVER_FILENAME);
+}
+
+/**
+ * Copy the bundled server into the stable path when missing or changed.
+ * Content comparison (not version plumbing) decides refreshes, so any
+ * bundle change propagates on next plugin startup. Returns the stable path.
+ */
+export function syncStableServer(
+  source: string = serverPath(),
+  dest: string = stableServerPath(),
+): string {
+  mkdirSync(dirname(dest), { recursive: true });
+  let current: Buffer | null = null;
+  try {
+    current = readFileSync(dest);
+  } catch {
+    current = null;
+  }
+  const next = readFileSync(source);
+  if (!current || !current.equals(next)) {
+    writeFileSync(dest, next, { mode: 0o755 });
+    log.info(`injection: installed stable server at ${dest}`);
+  }
+  return dest;
+}
+
+/**
+ * Resolve a JS runtime command for spawned MCP servers. Under Electron
+ * (ELECTRON_RUN_AS_NODE) process.execPath is the app GUI binary, which
+ * cannot execute scripts, so fall back to PATH-resolved node there.
+ */
+export function resolveNodeCommand(execPath: string): string {
+  const base = basename(execPath).toLowerCase();
+  if (/^(node|bun|deno)/.test(base)) {
+    return execPath;
+  }
+  return "node";
+}
+
+export interface InjectionGate {
+  enabled: boolean;
+}
+
+/**
+ * Adapt the SDK's generically-typed hook registry to the helper's
+ * string-typed structural registrar. The literal "agent.create" is a valid
+ * key of the SDK registry, so this is a type-level bridge only: merge
+ * semantics stay entirely inside the helper. Remove if the helper widens
+ * McpInjectionServer to accept the SDK BeforeRegistrar directly.
+ */
+export function toInjectionServer(server: PluginServerContext): McpInjectionServer {
+  return {
+    before: (name, handler) =>
+      (server.before as (
+        n: string,
+        h: McpInjectionHookHandler,
+      ) => () => void)(name, handler),
+  };
+}
+
+/**
+ * Register MCP injection when the daemon-wide toggle is on, otherwise do
+ * nothing. Toggle changes take effect on plugin reload. Returns the
+ * helper's remover for cleanup.
+ */
+export function maybeRegisterInjection(
+  server: McpInjectionServer,
+  gate: InjectionGate,
+  overrides?: { serverName?: string; config?: McpStdioInjectionConfig },
+): () => void {
+  if (!gate.enabled) {
+    log.info("injection: disabled by settings, skipping agent.create hook");
+    return () => {};
+  }
+  const serverName = overrides?.serverName ?? injectionServerName();
+  let config: McpStdioInjectionConfig;
+  try {
+    config = overrides?.config ?? injectionServerConfig();
+  } catch (cause) {
+    log.error(`injection: stable server unavailable, skipping agent.create hook: ${cause instanceof Error ? cause.message : String(cause)}`);
+    return () => {};
+  }
+  log.info(`injection: registering agent.create hook under key '${serverName}'`);
+  return registerMcpInjection(server, { serverName, config });
+}

package/server/local-send.ts

@@ -0,0 +1,153 @@
+import { hostname } from "node:os";
+import type { PaseoApi } from "@getpaseo/client";
+import { localServerId } from "./peer-channel";
+
+/**
+ * Native send for targets that live on THIS daemon.
+ *
+ * `PaseoApi.send()` is bound to one daemon connection — it carries no host or
+ * serverId (see PaseoAgentSendOptions) — so it can only reach agents on the
+ * daemon the handle was created for. The plugin server's `context.paseo` is
+ * exactly that local daemon handle. Remote peers still go through the bundled
+ * MCP server's `paseo send --host` path; there is no host-targeted SDK call.
+ *
+ * The envelope is the wire contract. This producer must stay byte-compatible
+ * with the MCP server's `senderMetaBlock` (mcp/paseo-x-comms.mjs), which stamps
+ * the remote path: same prefix, same version, same field set. `parseEnvelope`
+ * in shared/envelope.ts reads both.
+ */
+
+export const ENVELOPE_PREFIX = "[x-comms] ";
+
+/**
+ * Sending a message to your own agent is a mistake (the envelope tells the
+ * recipient it is from itself). Same fixed label the MCP server uses, so the
+ * failure is greppable and identical on both delivery paths.
+ */
+export const SELF_MESSAGE_LABEL = "x-comms self-message";
+
+export function assertNotSelfMessage(agentId: string, fromAgentId: string | null): void {
+  if (fromAgentId && agentId === fromAgentId) {
+    throw new Error(
+      `${SELF_MESSAGE_LABEL}: target agentId '${agentId}' is your own agent — choose a different agent.`,
+    );
+  }
+}
+
+export interface SenderIdentity {
+  agentId: string | null;
+  agentName: string | null;
+  host: string;
+  daemonServerId: string | null;
+  cwd: string | null;
+}
+
+export interface LocalSendInput {
+  agentId: string;
+  prompt: string;
+  fromAgentId?: string | null;
+  fromAgentName?: string | null;
+  targetDaemon: string;
+}
+
+/**
+ * Build the `[x-comms] {…}` envelope exactly as the MCP server's version-4
+ * stamp does. Pure so the contract is testable without a daemon.
+ */
+export function buildSenderEnvelope(args: {
+  sender: SenderIdentity;
+  target: { daemon: string | null; agentId: string | null };
+  sentAt: string;
+}): string {
+  const envelope = {
+    xComms: {
+      version: 4,
+      type: "x-comms.message",
+      direction: "outgoing",
+      sender: {
+        agentId: args.sender.agentId,
+        agentName: args.sender.agentName,
+        host: args.sender.host,
+        daemonServerId: args.sender.daemonServerId,
+        cwd: args.sender.cwd,
+      },
+      target: {
+        daemon: args.target.daemon ?? null,
+        agentId: args.target.agentId ?? null,
+      },
+      sentAt: args.sentAt,
+    },
+  };
+  return `${ENVELOPE_PREFIX}${JSON.stringify(envelope)}`;
+}
+
+/** True when a resolved target serverId is this daemon's own serverId. */
+export function isLocalIdentity(
+  targetServerId: string | null,
+  selfServerId: string | null,
+): boolean {
+  return targetServerId !== null && selfServerId !== null && targetServerId === selfServerId;
+}
+
+export type SendRoute = "local" | "remote";
+
+/**
+ * Pick the delivery path for a resolved target. Local requires all three: a
+ * local PaseoApi handle, a resolved target serverId, and a match with this
+ * daemon's serverId. Anything unresolved stays remote, so an unidentifiable
+ * direct host conservatively uses the CLI path rather than guessing.
+ */
+export function resolveSendRoute(args: {
+  hasLocalPaseo: boolean;
+  targetServerId: string | null;
+  selfServerId: string | null;
+}): SendRoute {
+  if (!args.hasLocalPaseo) return "remote";
+  return isLocalIdentity(args.targetServerId, args.selfServerId) ? "local" : "remote";
+}
+
+/**
+ * Best-effort sender identity for the local stamp. The sender agent's title
+ * and cwd come from its snapshot; a lookup failure degrades to null fields
+ * (the envelope stays valid, matching the MCP fallback behavior).
+ */
+export async function gatherLocalSenderIdentity(
+  paseo: PaseoApi,
+  input: Pick<LocalSendInput, "fromAgentId" | "fromAgentName">,
+): Promise<SenderIdentity> {
+  const agentId = input.fromAgentId ?? null;
+  let agentName = input.fromAgentName ?? null;
+  let cwd: string | null = null;
+  if (agentId) {
+    try {
+      const result = await paseo.agents.ref(agentId).refresh();
+      const agent = result?.agent ?? null;
+      if (!agentName) agentName = agent?.title ?? null;
+      cwd = agent?.cwd ?? null;
+    } catch {
+      // id-only identity is still a valid envelope.
+    }
+  }
+  let daemonServerId: string | null = null;
+  try {
+    daemonServerId = await localServerId();
+  } catch {
+    // unreadable server-id: omit it rather than fail the send.
+  }
+  return { agentId, agentName, host: hostname(), daemonServerId, cwd };
+}
+
+/**
+ * Send to a local agent via the native SDK. Mirrors `paseo send --no-wait`:
+ * `send()` dispatches the message and resolves without waiting for the turn.
+ */
+export async function sendLocalNative(paseo: PaseoApi, input: LocalSendInput): Promise<void> {
+  assertNotSelfMessage(input.agentId, input.fromAgentId ?? null);
+  const sender = await gatherLocalSenderIdentity(paseo, input);
+  const stamped = `${buildSenderEnvelope({
+    sender,
+    target: { daemon: input.targetDaemon, agentId: input.agentId },
+    sentAt: new Date().toISOString(),
+  })}\n\n${input.prompt}`;
+  await paseo.agents.ref(input.agentId).send(stamped);
+}

package/server/mcp-client.ts

@@ -0,0 +1,47 @@
+import { McpClient } from "paseo-plugin-helper/mcp";
+import { createPluginLogger } from "paseo-plugin-helper/server";
+
+const log = createPluginLogger("paseo-x-comms", { subsystem: "mcp-client" });
+
+/**
+ * Thin wrapper around the helper McpClient for talking to the installed
+ * paseo-x-comms server over stdio. Keeps the call sites stable: connect
+ * returns server info plus tool names, callTool returns parsed JSON payloads,
+ * and close releases the child process tree.
+ */
+export class McpStdioClient {
+  private readonly client: McpClient;
+
+  constructor(serverPath: string, args: string[] = []) {
+    this.client = McpClient.forStdio(process.execPath, [serverPath, ...args], undefined, {
+      clientInfo: { name: "paseo-x-comms", version: "0.3.0" },
+      timeoutMs: 15000,
+    });
+  }
+
+  async connect(): Promise<{ serverInfo: unknown; tools: Array<{ name: string }> }> {
+    await this.client.initialize();
+    const tools = await this.client.listTools();
+    return { serverInfo: this.client.serverInfo, tools: tools.map((tool) => ({ name: tool.name })) };
+  }
+
+  async callTool(name: string, arguments_: Record<string, unknown>): Promise<unknown> {
+    const result = await this.client.callTool(name, arguments_);
+    if (result.isError) {
+      const text = result.content?.map((part) => part.text ?? "").join("\n") ?? "tool error";
+      throw new Error(text.slice(0, 400));
+    }
+    const text = result.content?.map((part) => part.text ?? "").join("\n") ?? "";
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  close(): void {
+    this.client.close().catch((error: unknown) => {
+      log.error(`mcp client close failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+  }
+}

package/server/outbox.ts

@@ -0,0 +1,233 @@
+import { randomUUID } from "node:crypto";
+import { PluginStorage } from "paseo-plugin-helper/server";
+
+/**
+ * Outbox for outbound conversation messages that could not be delivered.
+ *
+ * Retry strategy: per-entry exponential backoff, a periodic sweep, and an
+ * explicit immediate retry when a peer is observed reconnecting. Entries expire
+ * after a configurable window; expiry notifies the local sender with the reason.
+ *
+ * Idempotency is deliberately absent: the conversation protocol has no
+ * message-UUID slot and receivers keep no seen-id set for messages (see #12),
+ * so a retry after an ambiguous failure can re-deliver. Retry, expiry, and
+ * notify only.
+ */
+
+export const OUTBOX_FILE = "outbox.json";
+export const DEFAULT_OUTBOX_EXPIRY_MS = 10 * 60 * 1000;
+export const OUTBOX_BACKOFF_BASE_MS = 5_000;
+export const OUTBOX_BACKOFF_MAX_MS = 60_000;
+export const OUTBOX_POLL_INTERVAL_MS = 15_000;
+
+export interface OutboxMessageInput {
+  daemon: string;
+  agentId: string;
+  prompt: string;
+  fromAgentId?: string | null;
+  fromAgentName?: string | null;
+}
+
+export interface OutboxEntry {
+  id: string;
+  daemon: string;
+  agentId: string;
+  prompt: string;
+  fromAgentId: string | null;
+  fromAgentName: string | null;
+  createdAt: string;
+  expiresAt: string;
+  attempts: number;
+  lastAttemptAt: string | null;
+  lastError: string | null;
+  nextAttemptAt: string;
+}
+
+export interface OutboxState {
+  entries: OutboxEntry[];
+}
+
+export function emptyOutboxState(): OutboxState {
+  return { entries: [] };
+}
+
+/**
+ * Delay before the next attempt after `attempts` failures:
+ * `base * 2^(attempts-1)`, capped at `maxMs`.
+ */
+export function outboxBackoffMs(
+  attempts: number,
+  baseMs: number = OUTBOX_BACKOFF_BASE_MS,
+  maxMs: number = OUTBOX_BACKOFF_MAX_MS,
+): number {
+  if (attempts <= 0) return 0;
+  return Math.min(baseMs * 2 ** (attempts - 1), maxMs);
+}
+
+export interface HoldOptions {
+  id?: string;
+  nowMs?: number;
+  expiryMs?: number;
+  /** Failure that caused the hold; counts as the first attempt. */
+  error?: string | null;
+}
+
+/** Append a held message and schedule its first retry after the backoff. */
+export function holdMessage(
+  state: OutboxState,
+  input: OutboxMessageInput,
+  options: HoldOptions = {},
+): OutboxEntry {
+  const nowMs = options.nowMs ?? Date.now();
+  const expiryMs = options.expiryMs ?? DEFAULT_OUTBOX_EXPIRY_MS;
+  const error = options.error ?? null;
+  const attempts = error ? 1 : 0;
+  const entry: OutboxEntry = {
+    id: options.id ?? randomUUID(),
+    daemon: input.daemon,
+    agentId: input.agentId,
+    prompt: input.prompt,
+    fromAgentId: input.fromAgentId ?? null,
+    fromAgentName: input.fromAgentName ?? null,
+    createdAt: new Date(nowMs).toISOString(),
+    expiresAt: new Date(nowMs + expiryMs).toISOString(),
+    attempts,
+    lastAttemptAt: attempts > 0 ? new Date(nowMs).toISOString() : null,
+    lastError: error,
+    nextAttemptAt: new Date(nowMs + outboxBackoffMs(attempts)).toISOString(),
+  };
+  state.entries.push(entry);
+  return entry;
+}
+
+export function dueEntries(state: OutboxState, nowMs: number): OutboxEntry[] {
+  return state.entries.filter((entry) => Date.parse(entry.nextAttemptAt) <= nowMs);
+}
+
+export function expiredEntries(state: OutboxState, nowMs: number): OutboxEntry[] {
+  return state.entries.filter((entry) => Date.parse(entry.expiresAt) <= nowMs);
+}
+
+export function removeEntries(state: OutboxState, ids: Iterable<string>): void {
+  const drop = new Set(ids);
+  state.entries = state.entries.filter((entry) => !drop.has(entry.id));
+}
+
+export interface OutboxDelivery {
+  /** Resolve when delivered; reject to schedule a backoff retry. */
+  deliver(entry: OutboxEntry): Promise<void>;
+  /** Best-effort notice to the sender for an entry that expired. */
+  notify(entry: OutboxEntry, reason: string): Promise<void>;
+}
+
+export interface OutboxPassOptions {
+  nowMs?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  /** Retry every held entry for this daemon immediately (peer reconnect). */
+  forceDaemon?: string;
+}
+
+export interface OutboxPassResult {
+  delivered: string[];
+  retried: string[];
+  expired: string[];
+  notified: string[];
+  notifyFailed: string[];
+}
+
+export function formatOutboxDuration(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+}
+
+export function outboxExpiryReason(entry: OutboxEntry, nowMs: number): string {
+  const held = formatOutboxDuration(nowMs - Date.parse(entry.createdAt));
+  const attempts = entry.attempts === 1 ? "1 attempt" : `${entry.attempts} attempts`;
+  const last = entry.lastError ? `; last error: ${entry.lastError}` : "";
+  return `could not deliver to '${entry.daemon}/${entry.agentId}' after ${held} (${attempts}${last})`;
+}
+
+/**
+ * One sweep: expire overdue entries (notify the sender, then drop), then retry
+ * every due entry once. Mutates `state`; returns what happened.
+ */
+export async function runOutboxPass(
+  state: OutboxState,
+  delivery: OutboxDelivery,
+  options: OutboxPassOptions = {},
+): Promise<OutboxPassResult> {
+  const nowMs = options.nowMs ?? Date.now();
+  const baseMs = options.baseDelayMs ?? OUTBOX_BACKOFF_BASE_MS;
+  const maxMs = options.maxDelayMs ?? OUTBOX_BACKOFF_MAX_MS;
+  const result: OutboxPassResult = {
+    delivered: [],
+    retried: [],
+    expired: [],
+    notified: [],
+    notifyFailed: [],
+  };
+
+  const expired = expiredEntries(state, nowMs);
+  for (const entry of expired) {
+    const reason = outboxExpiryReason(entry, nowMs);
+    try {
+      await delivery.notify(entry, reason);
+      result.notified.push(entry.id);
+    } catch {
+      result.notifyFailed.push(entry.id);
+    }
+  }
+  removeEntries(state, expired.map((entry) => entry.id));
+  result.expired.push(...expired.map((entry) => entry.id));
+
+  if (options.forceDaemon) {
+    const forcedAt = new Date(nowMs).toISOString();
+    for (const entry of state.entries) {
+      if (entry.daemon === options.forceDaemon) entry.nextAttemptAt = forcedAt;
+    }
+  }
+
+  for (const entry of dueEntries(state, nowMs)) {
+    try {
+      await delivery.deliver(entry);
+      removeEntries(state, [entry.id]);
+      result.delivered.push(entry.id);
+    } catch (cause) {
+      entry.attempts += 1;
+      entry.lastAttemptAt = new Date(nowMs).toISOString();
+      entry.lastError = cause instanceof Error ? cause.message : String(cause);
+      entry.nextAttemptAt = new Date(nowMs + outboxBackoffMs(entry.attempts, baseMs, maxMs)).toISOString();
+      result.retried.push(entry.id);
+    }
+  }
+
+  return result;
+}
+
+const outboxStore = new PluginStorage<OutboxState>("paseo-x-comms", OUTBOX_FILE, {
+  defaultData: emptyOutboxState(),
+});
+
+export function outboxPath(): string {
+  return outboxStore.filePath;
+}
+
+export function readOutbox(): OutboxState {
+  try {
+    const data = outboxStore.read();
+    if (data && typeof data === "object" && Array.isArray(data.entries)) {
+      return { entries: data.entries as OutboxEntry[] };
+    }
+  } catch {
+    // Corrupt state falls back to empty; the held message is lost and logged by callers.
+  }
+  return emptyOutboxState();
+}
+
+export function writeOutbox(state: OutboxState): void {
+  outboxStore.write(state);
+}