@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/src/pi-intercom/broker/pid.ts

@@ -0,0 +1,59 @@
+import { closeSync, openSync, readFileSync, readlinkSync } from "node:fs";
+
+// Keep the first numeric line readable by older brokers/spawn guards.
+// starttime is /proc/<pid>/stat field 22, in clock ticks; never round it to Number.
+const IDENTITY = /^linux-v1 ([0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}) (pid:\[\d+\]) (time:\[\d+\]) (\d+)$/;
+
+export function readLinuxProcess(pid: number): { tgid: number; identity?: string } | undefined {
+  if (process.platform !== "linux") return undefined;
+  let fd: number | undefined;
+  try {
+    // A procfs mounted from an ancestor PID namespace has different PID numbers
+    // from kill(2)/process.pid. Do not use that view to disprove broker identity.
+    const self = readFileSync("/proc/self/status", "utf8");
+    if (!new RegExp(`^NStgid:[ \\t]+${process.pid}$`, "m").test(self)) return undefined;
+    // Pin this proc directory so separate metadata reads cannot cross PID reuse.
+    fd = openSync(`/proc/${pid}`, "r");
+    const base = `/proc/self/fd/${fd}`;
+    const status = readFileSync(`${base}/status`, "utf8");
+    const tgid = Number(/^Tgid:[ \t]+(\d+)$/m.exec(status)?.[1]);
+    if (!Number.isSafeInteger(tgid) || tgid <= 0
+      || Number(/^Pid:[ \t]+(\d+)$/m.exec(status)?.[1]) !== pid) return undefined;
+    // Node writes process.pid (the thread-group leader), never a worker TID.
+    if (tgid !== pid) return { tgid };
+    const stat = readFileSync(`${base}/stat`, "utf8");
+    // comm can contain spaces, newlines and ')'; fields after its final ')' are fixed.
+    if (!stat.startsWith(`${pid} (`)) return undefined;
+    const startTicks = stat.slice(stat.lastIndexOf(")") + 2).split(/\s+/)[19];
+    const bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    const pidNamespace = readlinkSync(`${base}/ns/pid`);
+    // Linux applies the *reader's* time-namespace offset to stat.starttime.
+    const timeNamespace = readlinkSync("/proc/self/ns/time");
+    const identity = `linux-v1 ${bootId} ${pidNamespace} ${timeNamespace} ${startTicks}`;
+    return IDENTITY.test(identity) ? { tgid, identity } : undefined;
+  } catch {
+    // Unavailable procfs, permissions or incomplete observations prove nothing.
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function brokerPidRecord(): string {
+  const identity = readLinuxProcess(process.pid)?.identity;
+  return `${process.pid}\n${identity ? `${identity}\n` : ""}`;
+}
+
+export function isBrokerPidReused(pid: number, record: string): boolean {
+  const current = readLinuxProcess(pid);
+  if (!current) return false;
+  if (current.tgid !== pid) return true;
+  const saved = IDENTITY.exec(record.slice(record.indexOf("\n") + 1).trim());
+  const actual = IDENTITY.exec(current.identity ?? "");
+  if (!saved || !actual) return false;
+  const [, boot, namespace, clock, start] = saved;
+  const [, actualBoot, actualNamespace, actualClock, actualStart] = actual;
+  // A clock-namespace change alone is not evidence that the process changed.
+  return boot !== actualBoot || namespace !== actualNamespace
+    || (clock === actualClock && start !== actualStart);
+}

package/src/pi-intercom/broker/spawn.ts

@@ -0,0 +1,248 @@
+import { spawn } from "child_process";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { mkdir } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import net from "net";
+import { getPiAgentDir } from "../agent-dir.ts";
+import { getBrokerSocketPath, getLegacyBrokerSocketPath, isOwnedBrokerSocket } from "./paths.ts";
+import { isBrokerPidReused } from "./pid.ts";
+
+const INTERCOM_DIR = join(getPiAgentDir(), "intercom");
+const EXTENSION_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const BROKER_PID = join(INTERCOM_DIR, "broker.pid");
+const BROKER_SPAWN_LOCK = join(INTERCOM_DIR, "broker.spawn.lock");
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function usesLegacyTsxDefault(brokerCommand: string, brokerArgs: string[]): boolean {
+  return brokerCommand === "npx"
+    && brokerArgs.length === 2
+    && brokerArgs[0] === "--no-install"
+    && brokerArgs[1] === "tsx";
+}
+
+export function getBrokerLaunchSpec(
+  brokerPath: string,
+  brokerCommand: string,
+  brokerArgs: string[],
+): { command: string; args: string[] } {
+  if (usesLegacyTsxDefault(brokerCommand, brokerArgs)) {
+    return {
+      command: process.execPath,
+      args: [brokerPath],
+    };
+  }
+
+  return {
+    command: brokerCommand,
+    args: [...brokerArgs, brokerPath],
+  };
+}
+
+export function getBrokerSpawnOptions(): {
+  detached: true;
+  stdio: "ignore";
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+} {
+  return {
+    detached: true,
+    stdio: "ignore",
+    cwd: EXTENSION_DIR,
+    env: { ...process.env, NODE_NO_WARNINGS: "1" },
+  };
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: string[]): Promise<void> {
+  await mkdir(INTERCOM_DIR, { recursive: true });
+
+  if (await isBrokerRunning()) {
+    return;
+  }
+
+  const ownsLock = acquireSpawnLock();
+  if (!ownsLock) {
+    await waitForBroker();
+    return;
+  }
+
+  try {
+    if (await isBrokerRunning()) {
+      return;
+    }
+    await stopUnhealthyBrokerBeforeSpawn();
+
+    const brokerPath = join(
+      dirname(fileURLToPath(import.meta.url)),
+      import.meta.url.endsWith(".ts") ? "broker.ts" : "broker.js",
+    );
+    const launch = getBrokerLaunchSpec(brokerPath, brokerCommand, brokerArgs);
+    const child = spawn(launch.command, launch.args, getBrokerSpawnOptions());
+    child.unref();
+
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = () => {
+        child.off("error", onError);
+        child.off("exit", onExit);
+      };
+
+      const onError = (error: Error) => {
+        cleanup();
+        reject(new Error(`Failed to spawn intercom broker: ${error.message}`, { cause: error }));
+      };
+
+      const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
+        cleanup();
+        if (signal) {
+          reject(new Error(`Intercom broker exited before startup with signal ${signal}`));
+          return;
+        }
+        reject(new Error(`Intercom broker exited before startup with code ${code ?? "unknown"}`));
+      };
+
+      child.once("error", onError);
+      child.once("exit", onExit);
+      waitForBroker().then(() => {
+        cleanup();
+        resolve();
+      }, (error) => {
+        cleanup();
+        reject(toError(error));
+      });
+    });
+  } finally {
+    releaseSpawnLock();
+  }
+}
+
+export async function isBrokerRunning(): Promise<boolean> {
+  return checkSocketConnectable();
+}
+
+function readLivePid(): number | null {
+  if (!existsSync(BROKER_PID)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(BROKER_PID, "utf-8");
+  } catch {
+    return null;
+  }
+  const pid = parseInt(raw.trim(), 10);
+  if (!Number.isFinite(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM" ? pid : null;
+  }
+  return isBrokerPidReused(pid, raw) ? null : pid;
+}
+
+export async function stopUnhealthyBrokerBeforeSpawn(): Promise<void> {
+  if (await checkSocketConnectable()) return;
+  const pid = readLivePid();
+  if (pid === null) return;
+  throw new Error(`Intercom broker PID ${pid} may still own accepted work but its socket is unhealthy; refusing to spawn a second broker. Let the broker exit normally, then retry.`);
+}
+
+async function checkSocketConnectable(): Promise<boolean> {
+  const preferred = getBrokerSocketPath();
+  if (isOwnedBrokerSocket(preferred) && await checkOneSocket(preferred)) return true;
+  const legacy = getLegacyBrokerSocketPath();
+  return legacy !== preferred && isOwnedBrokerSocket(legacy) && await checkOneSocket(legacy);
+}
+
+function checkOneSocket(brokerSocket: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect(brokerSocket);
+    const finish = (isConnected: boolean) => {
+      clearTimeout(timeout);
+      socket.off("connect", onConnect);
+      socket.off("error", onError);
+      socket.destroy();
+      resolve(isConnected);
+    };
+    const onConnect = () => finish(true);
+    const onError = () => finish(false);
+    socket.on("connect", onConnect);
+    socket.on("error", onError);
+    const timeout = setTimeout(() => finish(false), 1000);
+    timeout.unref?.();
+  });
+}
+
+function acquireSpawnLock(): boolean {
+  const maxRetries = 5;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      writeFileSync(BROKER_SPAWN_LOCK, `${process.pid}\n${Date.now()}\n`, { flag: "wx" });
+      return true;
+    } catch (error) {
+      if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (isSpawnLockStale()) {
+        try {
+          unlinkSync(BROKER_SPAWN_LOCK);
+        } catch {
+          // If we can't delete the stale lock, retry a few times before giving up
+        }
+        continue;
+      }
+      return false;
+    }
+  }
+  return false;
+}
+
+function isSpawnLockStale(): boolean {
+  if (!existsSync(BROKER_SPAWN_LOCK)) {
+    return false;
+  }
+
+  try {
+    const [pidLine = "", createdAtLine = "0"] = readFileSync(BROKER_SPAWN_LOCK, "utf-8").trim().split("\n");
+    const pid = Number.parseInt(pidLine, 10);
+    const createdAt = Number.parseInt(createdAtLine, 10);
+    const ageMs = Date.now() - createdAt;
+
+    if (Number.isFinite(pid)) {
+      try {
+        process.kill(pid, 0);
+      } catch {
+        // The process that created the lock is gone.
+        return true;
+      }
+    }
+
+    return !Number.isFinite(createdAt) || ageMs > 10_000;
+  } catch {
+    // Unreadable lock contents are treated as stale so a new broker can start.
+    return true;
+  }
+}
+
+function releaseSpawnLock(): void {
+  try {
+    unlinkSync(BROKER_SPAWN_LOCK);
+  } catch {
+    // Another cleanup path may already have removed the lock.
+  }
+}
+
+async function waitForBroker(timeoutMs = 5000): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await checkSocketConnectable()) {
+      return;
+    }
+    await sleep(100);
+  }
+  throw new Error("Broker failed to start within timeout");
+}

package/src/pi-intercom/config.ts

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { Key, type KeyId } from "@earendil-works/pi-tui";
+import { getPiAgentDir } from "./agent-dir.ts";
+
+export interface IntercomConfig {
+  /** Toggle owned agents, or open peer messaging when the agent view is unavailable. */
+  shortcut: KeyId;
+
+  /** Broker command used to spawn the broker process (for example, Node or Bun) */
+  brokerCommand: string;
+
+  /** Arguments passed to the broker command before the broker script path */
+  brokerArgs: string[];
+
+  /** Require confirmation before non-reply sends from interactive sessions */
+  confirmSend: boolean;
+
+  /** Optional custom status suffix shown after automatic lifecycle status */
+  status?: string;
+
+  /** Show reply hint in incoming messages (default: true) */
+  replyHint: boolean;
+
+  /** How long ordinary intercom `ask` waits for a reply before giving up, in ms (default: 120000 = 2 minutes). */
+  askTimeoutMs: number;
+
+  /** How long the client waits for the broker to acknowledge message delivery, in ms (default: 8000). */
+  sendTimeoutMs: number;
+
+  /** How long the client waits for a session list response, in ms (default: 5000). */
+  listTimeoutMs: number;
+}
+
+function getConfigPath(): string {
+  return join(getPiAgentDir(), "intercom", "config.json");
+}
+
+const defaults: IntercomConfig = {
+  shortcut: Key.altShift("m"),
+  brokerCommand: process.execPath,
+  brokerArgs: [],
+  confirmSend: false,
+  replyHint: true,
+  askTimeoutMs: 2 * 60 * 1000,
+  sendTimeoutMs: 8000,
+  listTimeoutMs: 5000,
+};
+
+const namedKeys = new Set<string>(Object.values(Key).filter((key) => typeof key === "string"));
+function isShortcut(value: string): value is KeyId {
+  const prefix = value.match(/^(?:(?:ctrl|shift|alt|super)\+)+/)?.[0] ?? "";
+  const modifiers = prefix.split("+").filter(Boolean);
+  const key = value.slice(prefix.length);
+  return new Set(modifiers).size === modifiers.length && (namedKeys.has(key) || /^[a-z0-9]$/.test(key));
+}
+
+export function loadConfig(): IntercomConfig {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    return { ...defaults };
+  }
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("Config must be a JSON object");
+    }
+
+    const parsedConfig = parsed as Record<string, unknown>;
+    const config: IntercomConfig = { ...defaults };
+
+    if (Object.hasOwn(parsedConfig, "shortcut")) {
+      if (typeof parsedConfig.shortcut !== "string") throw new Error('"shortcut" must be a native key identifier');
+      const shortcut = parsedConfig.shortcut.trim();
+      if (!isShortcut(shortcut)) throw new Error('"shortcut" must be a native key identifier, for example alt+shift+m');
+      config.shortcut = shortcut;
+    }
+
+    if (Object.hasOwn(parsedConfig, "brokerCommand")) {
+      if (typeof parsedConfig.brokerCommand !== "string") {
+        throw new Error(`"brokerCommand" must be a string`);
+      }
+      const brokerCommand = parsedConfig.brokerCommand.trim();
+      if (!brokerCommand) {
+        throw new Error(`"brokerCommand" must not be empty`);
+      }
+      config.brokerCommand = brokerCommand;
+    }
+
+    if (Object.hasOwn(parsedConfig, "brokerArgs")) {
+      if (!Array.isArray(parsedConfig.brokerArgs)) {
+        throw new Error(`"brokerArgs" must be an array`);
+      }
+      const brokerArgs: string[] = [];
+      for (const arg of parsedConfig.brokerArgs) {
+        if (typeof arg !== "string") {
+          throw new Error(`"brokerArgs" items must be strings`);
+        }
+        brokerArgs.push(arg);
+      }
+      config.brokerArgs = brokerArgs;
+    }
+
+    if (Object.hasOwn(parsedConfig, "confirmSend")) {
+      if (typeof parsedConfig.confirmSend !== "boolean") {
+        throw new Error(`"confirmSend" must be a boolean`);
+      }
+      config.confirmSend = parsedConfig.confirmSend;
+    }
+
+    if (Object.hasOwn(parsedConfig, "replyHint")) {
+      if (typeof parsedConfig.replyHint !== "boolean") {
+        throw new Error(`"replyHint" must be a boolean`);
+      }
+      config.replyHint = parsedConfig.replyHint;
+    }
+
+    if (Object.hasOwn(parsedConfig, "status")) {
+      if (typeof parsedConfig.status !== "string") {
+        throw new Error(`"status" must be a string`);
+      }
+      config.status = parsedConfig.status;
+    }
+
+    for (const [key, min] of [["askTimeoutMs", 1000], ["sendTimeoutMs", 500], ["listTimeoutMs", 500]] as const) {
+      if (Object.hasOwn(parsedConfig, key)) {
+        const value = parsedConfig[key];
+        if (typeof value !== "number" || !Number.isFinite(value) || value < min) {
+          throw new Error(`"${key}" must be a finite number >= ${min}`);
+        }
+        config[key] = value;
+      }
+    }
+
+    return config;
+  } catch (error) {
+    console.error(`Failed to load intercom config at ${configPath}:`, error);
+    return { ...defaults };
+  }
+}