pi-gang 0.1.0

package/src/intercom/broker/spawn.ts

@@ -0,0 +1,309 @@
+import { spawn } from "child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+import net from "net";
+import { getBrokerSocketPath } from "./paths.js";
+
+const INTERCOM_DIR = join(homedir(), ".pi/agent/intercom");
+const EXTENSION_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+const BROKER_SOCKET = getBrokerSocketPath();
+const BROKER_PID = join(INTERCOM_DIR, "broker.pid");
+const BROKER_SPAWN_LOCK = join(INTERCOM_DIR, "broker.spawn.lock");
+
+type BrokerLaunchSpec =
+  | {
+    kind: "direct";
+    command: string;
+    args: string[];
+  }
+  | {
+    kind: "windows-launcher";
+    command: string;
+    args: string[];
+    launcherPath: string;
+    launcherCommandLine: string;
+  };
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export function getTsxCliPath(extensionDir: string = EXTENSION_DIR): string {
+  return join(extensionDir, "node_modules", "tsx", "dist", "cli.mjs");
+}
+
+function quoteWindowsArg(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+export function getWindowsHiddenLauncherPath(intercomDir: string = INTERCOM_DIR): string {
+  return join(intercomDir, "broker-launch.vbs");
+}
+
+function usesDefaultBrokerCommand(brokerCommand: string, brokerArgs: string[]): boolean {
+  return brokerCommand === "npx"
+    && brokerArgs.length === 2
+    && brokerArgs[0] === "--no-install"
+    && brokerArgs[1] === "tsx";
+}
+
+export function getWindowsBrokerCommandLine(
+  brokerPath: string,
+  extensionDir: string = EXTENSION_DIR,
+  nodePath: string = process.execPath,
+  brokerCommand = "npx",
+  brokerArgs: string[] = ["--no-install", "tsx"],
+): string {
+  if (usesDefaultBrokerCommand(brokerCommand, brokerArgs)) {
+    return [quoteWindowsArg(nodePath), quoteWindowsArg(getTsxCliPath(extensionDir)), quoteWindowsArg(brokerPath)].join(" ");
+  }
+
+  return [quoteWindowsArg(brokerCommand), ...brokerArgs.map(quoteWindowsArg), quoteWindowsArg(brokerPath)].join(" ");
+}
+
+export function getWindowsHiddenLauncherScript(commandLine: string): string {
+  return [
+    'Set WshShell = CreateObject("WScript.Shell")',
+    `WshShell.Run "${commandLine.replace(/"/g, '""')}", 0, False`,
+    'Set WshShell = Nothing',
+    '',
+  ].join("\r\n");
+}
+
+function writeWindowsHiddenLauncher(
+  commandLine: string,
+  launcherPath: string = getWindowsHiddenLauncherPath(),
+): string {
+  mkdirSync(dirname(launcherPath), { recursive: true, mode: 0o700 });
+  writeFileSync(launcherPath, getWindowsHiddenLauncherScript(commandLine), { encoding: "utf-8", mode: 0o600 });
+  return launcherPath;
+}
+
+export function getBrokerLaunchSpec(
+  brokerPath: string,
+  brokerCommand: string,
+  brokerArgs: string[],
+  extensionDir: string = EXTENSION_DIR,
+  platform: NodeJS.Platform = process.platform,
+  intercomDir: string = INTERCOM_DIR,
+  nodePath: string = process.execPath,
+): BrokerLaunchSpec {
+  if (platform === "win32") {
+    const launcherPath = getWindowsHiddenLauncherPath(intercomDir);
+    return {
+      kind: "windows-launcher",
+      command: "wscript.exe",
+      args: [launcherPath],
+      launcherPath,
+      launcherCommandLine: getWindowsBrokerCommandLine(brokerPath, extensionDir, nodePath, brokerCommand, brokerArgs),
+    };
+  }
+
+  return {
+    kind: "direct",
+    command: brokerCommand,
+    args: [...brokerArgs, brokerPath],
+  };
+}
+
+export function getBrokerSpawnOptions(extensionDir: string = EXTENSION_DIR): {
+  detached: true;
+  stdio: "ignore";
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  windowsHide: true;
+} {
+  return {
+    detached: true,
+    stdio: "ignore",
+    cwd: extensionDir,
+    env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    windowsHide: true,
+  };
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: string[]): Promise<void> {
+  mkdirSync(INTERCOM_DIR, { recursive: true, mode: 0o700 });
+  if (process.platform !== "win32") chmodSync(INTERCOM_DIR, 0o700);
+
+  if (await isBrokerRunning()) {
+    return;
+  }
+
+  const ownsLock = acquireSpawnLock();
+  if (!ownsLock) {
+    await waitForBroker();
+    return;
+  }
+
+  try {
+    if (await isBrokerRunning()) {
+      return;
+    }
+
+    const brokerPath = join(dirname(fileURLToPath(import.meta.url)), "broker.ts");
+    const launch = getBrokerLaunchSpec(brokerPath, brokerCommand, brokerArgs);
+    if (launch.kind === "windows-launcher") {
+      writeWindowsHiddenLauncher(launch.launcherCommandLine, launch.launcherPath);
+    }
+    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) => {
+        if (launch.kind === "windows-launcher" && code === 0 && signal === null) {
+          return;
+        }
+        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();
+  }
+}
+
+async function isBrokerRunning(): Promise<boolean> {
+  if (await checkSocketConnectable()) {
+    return true;
+  }
+
+  if (!existsSync(BROKER_PID)) return false;
+
+  try {
+    const pid = parseInt(readFileSync(BROKER_PID, "utf-8").trim(), 10);
+    if (!Number.isFinite(pid)) return false;
+    process.kill(pid, 0);
+    return checkSocketConnectable();
+  } catch {
+    // Missing or unreadable PID state means there is no live broker to reuse.
+    return false;
+  }
+}
+
+function checkSocketConnectable(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect(BROKER_SOCKET);
+    const finish = (isConnected: boolean) => {
+      clearTimeout(timeout);
+      socket.off("connect", onConnect);
+      socket.off("error", onError);
+      resolve(isConnected);
+    };
+    const onConnect = () => {
+      socket.end();
+      finish(true);
+    };
+    const onError = () => {
+      socket.destroy();
+      finish(false);
+    };
+    socket.on("connect", onConnect);
+    socket.on("error", onError);
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      finish(false);
+    }, 1000);
+  });
+}
+
+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", mode: 0o600 });
+      if (process.platform !== "win32") chmodSync(BROKER_SPAWN_LOCK, 0o600);
+      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/intercom/broker/tap.ts

@@ -0,0 +1,31 @@
+import { appendFileSync, chmodSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+
+/** One durable record per routed cross-agent message. */
+export interface RoutedLogEntry {
+  ts: number;
+  id: string;
+  from: string;
+  to: string;
+  text: string;
+  replyTo?: string;
+  expectsReply?: boolean;
+}
+
+export function getIntercomLogPath(homeDir: string = homedir()): string {
+  return join(homeDir, ".pi/agent/intercom/intercom.jsonl");
+}
+
+/** Append one greppable, replayable JSONL line. Best-effort: never break routing. */
+export function appendIntercomLog(entry: RoutedLogEntry, logPath: string = getIntercomLogPath()): void {
+  try {
+    const dir = dirname(logPath);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") chmodSync(dir, 0o700);
+    appendFileSync(logPath, JSON.stringify(entry) + "\n", { mode: 0o600 });
+    if (process.platform !== "win32") chmodSync(logPath, 0o600);
+  } catch {
+    // ponytail: observability is best-effort; a failed log write must not drop a message.
+  }
+}

package/src/intercom/config.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+export interface IntercomConfig {
+  /** Broker command used to spawn the broker process (e.g. "npx" 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;
+  
+  /** Enable/disable intercom (default: true) */
+  enabled: boolean;
+  
+  /** Show reply hint in incoming messages (default: true) */
+  replyHint: boolean;
+}
+
+const CONFIG_PATH = join(homedir(), ".pi/agent/intercom/config.json");
+
+const defaults: IntercomConfig = {
+  brokerCommand: "npx",
+  brokerArgs: ["--no-install", "tsx"],
+  confirmSend: false,
+  enabled: true,
+  replyHint: true,
+};
+
+export function loadConfig(): IntercomConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    return { ...defaults };
+  }
+  
+  try {
+    const raw = readFileSync(CONFIG_PATH, "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, "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, "enabled")) {
+      if (typeof parsedConfig.enabled !== "boolean") {
+        throw new Error(`"enabled" must be a boolean`);
+      }
+      config.enabled = parsedConfig.enabled;
+    }
+
+    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;
+    }
+
+    return config;
+  } catch (error) {
+    console.error(`Failed to load intercom config at ${CONFIG_PATH}:`, error);
+    return { ...defaults };
+  }
+}