@ctliz/agent-intercom-pi 0.11.0-connect.2

package/broker/spawn.ts

@@ -0,0 +1,448 @@
+import { spawn } from "child_process";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+import net from "net";
+import { randomUUID } from "crypto";
+import { POLICY_SEMANTICS_VERSION } from "@ctliz/agent-intercom-core/policy";
+import { POLICY_SEMANTICS_HASH } from "@ctliz/agent-intercom-core/vectors";
+import { createMessageReader, writeMessage } from "./framing.ts";
+import {
+  ensureIntercomRuntimeDir,
+  getAgentDirPath,
+  getBrokerConnectTarget,
+  getIntercomDirPath,
+  INTERCOM_PROTOCOL_NAME,
+  INTERCOM_PROTOCOL_VERSION,
+  INTERCOM_RUNTIME_FILE_MODE,
+  restrictIntercomRuntimeFile,
+  type BrokerConnectTarget,
+} from "./paths.ts";
+
+const INTERCOM_DIR = getIntercomDirPath();
+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");
+
+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 {
+  // Resolve tsx via Node's module resolution so it works regardless of whether
+  // tsx is bundled under extensionDir/node_modules or hoisted to a workspace
+  // root by npm. We resolve the tsx package main entry (its "exports" field
+  // does not expose ./dist/cli.mjs as a subpath) and then locate cli.mjs next
+  // to it. Falls back to the legacy relative path if resolution fails.
+  try {
+    const requireFromExtension = createRequire(import.meta.url);
+    const tsxMain = requireFromExtension.resolve("tsx");
+    return join(dirname(tsxMain), "cli.mjs");
+  } catch {
+    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");
+}
+
+export function isBrokerHealthOkMessage(message: unknown, requestId: string): boolean {
+  if (typeof message !== "object" || message === null || !("type" in message)) {
+    return false;
+  }
+  const response = message as Record<string, unknown>;
+  if (
+    response.type !== "health_ok"
+    || response.requestId !== requestId
+    || response.protocol !== INTERCOM_PROTOCOL_NAME
+    || response.version !== INTERCOM_PROTOCOL_VERSION
+    || response.endpoint !== "local"
+  ) return false;
+  const remoteAccess = response.remoteAccess;
+  if (typeof remoteAccess !== "object" || remoteAccess === null || Array.isArray(remoteAccess)) return false;
+  const contract = remoteAccess as Record<string, unknown>;
+  return contract.feature === "remote-access-v1"
+    && contract.policySemanticsVersion === POLICY_SEMANTICS_VERSION
+    && contract.policySemanticsHash === POLICY_SEMANTICS_HASH;
+}
+
+function writeWindowsHiddenLauncher(
+  commandLine: string,
+  launcherPath: string = getWindowsHiddenLauncherPath(),
+): string {
+  ensureIntercomRuntimeDir(dirname(launcherPath));
+  writeFileSync(launcherPath, getWindowsHiddenLauncherScript(commandLine), {
+    encoding: "utf-8",
+    mode: INTERCOM_RUNTIME_FILE_MODE,
+  });
+  restrictIntercomRuntimeFile(launcherPath);
+  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),
+    };
+  }
+
+  if (usesDefaultBrokerCommand(brokerCommand, brokerArgs)) {
+    return {
+      kind: "direct",
+      command: nodePath,
+      args: [getTsxCliPath(extensionDir), brokerPath],
+    };
+  }
+
+  return {
+    kind: "direct",
+    command: brokerCommand,
+    args: [...brokerArgs, brokerPath],
+  };
+}
+
+export function getBrokerSpawnOptions(
+  extensionDir: string = EXTENSION_DIR,
+  env: NodeJS.ProcessEnv = process.env,
+): {
+  detached: true;
+  stdio: "ignore";
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  windowsHide: true;
+} {
+  return {
+    detached: true,
+    stdio: "ignore",
+    cwd: extensionDir,
+    env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(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> {
+  ensureIntercomRuntimeDir(INTERCOM_DIR);
+
+  if (await isBrokerRunning()) {
+    return;
+  }
+
+  const ownsLock = acquireSpawnLock();
+  if (!ownsLock) {
+    await waitForBroker();
+    return;
+  }
+
+  try {
+    if (await isBrokerRunning()) {
+      return;
+    }
+    if (await checkBrokerHealth() === "incompatible") {
+      throw new Error(`Incompatible live intercom broker; expected ${INTERCOM_PROTOCOL_NAME} v${INTERCOM_PROTOCOL_VERSION}. Stop it explicitly during a coordinated migration.`);
+    }
+
+    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();
+  }
+}
+
+export async function stopBrokerProcess(pidFile = BROKER_PID, timeoutMs = 3000): Promise<void> {
+  if (!existsSync(pidFile)) return;
+  let pid: number;
+  try {
+    pid = Number.parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+  } catch {
+    return;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid) return;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return;
+  }
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      process.kill(pid, 0);
+      await sleep(50);
+    } catch {
+      return;
+    }
+  }
+  throw new Error(`Incompatible intercom broker ${pid} did not stop within ${timeoutMs}ms`);
+}
+
+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 connectToBrokerTarget(target: BrokerConnectTarget): net.Socket {
+  return typeof target === "string"
+    ? net.connect(target)
+    : net.connect({ host: target.host, port: target.port });
+}
+
+type BrokerHealth = "compatible" | "incompatible" | "unreachable";
+
+async function checkSocketConnectable(): Promise<boolean> {
+  return await checkBrokerHealth() === "compatible";
+}
+
+function checkBrokerHealth(): Promise<BrokerHealth> {
+  return new Promise((resolve) => {
+    let target: BrokerConnectTarget;
+    try {
+      target = getBrokerConnectTarget();
+    } catch {
+      resolve("unreachable");
+      return;
+    }
+
+    const socket = connectToBrokerTarget(target);
+    const requestId = randomUUID();
+    const expectedStateId = typeof target === "string" ? undefined : target.stateId;
+    let settled = false;
+    const finish = (health: BrokerHealth) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      socket.off("connect", onConnect);
+      socket.off("error", onError);
+      socket.off("data", reader);
+      socket.destroy();
+      resolve(health);
+    };
+    const onConnect = () => {
+      try {
+        writeMessage(socket, {
+          type: "health",
+          requestId,
+          ...(expectedStateId ? { stateId: expectedStateId } : {}),
+        });
+      } catch {
+        finish("unreachable");
+      }
+    };
+    const onError = () => finish("unreachable");
+    const reader = createMessageReader((message) => {
+      if (isBrokerHealthOkMessage(message, requestId)) {
+        finish("compatible");
+        return;
+      }
+      if (
+        typeof message === "object"
+        && message !== null
+        && "type" in message
+        && message.type === "health_ok"
+        && "requestId" in message
+        && message.requestId === requestId
+      ) {
+        finish("incompatible");
+        return;
+      }
+      finish("unreachable");
+    }, () => finish("unreachable"));
+    socket.on("connect", onConnect);
+    socket.on("error", onError);
+    socket.on("data", reader);
+    const timeout = setTimeout(() => finish("unreachable"), 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: INTERCOM_RUNTIME_FILE_MODE,
+      });
+      restrictIntercomRuntimeFile(BROKER_SPAWN_LOCK);
+      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/config.ts

@@ -0,0 +1,183 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { getIntercomDirPath } from "./broker/paths.ts";
+
+export const DEFAULT_ASK_TIMEOUT_MS = 10 * 60 * 1000;
+export const DEFAULT_ASK_WAIT_MS = 30 * 1000;
+
+export function getAskWaitMs(): number {
+  const raw = process.env.PI_INTERCOM_ASK_WAIT_MS;
+  if (raw === undefined || raw.trim() === "") {
+    return DEFAULT_ASK_WAIT_MS;
+  }
+
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error("PI_INTERCOM_ASK_WAIT_MS must be a positive integer number of milliseconds");
+  }
+  return value;
+}
+
+export function getAskTimeoutMs(): number {
+  const raw = process.env.PI_INTERCOM_ASK_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "") {
+    return DEFAULT_ASK_TIMEOUT_MS;
+  }
+
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error("PI_INTERCOM_ASK_TIMEOUT_MS must be a positive integer number of milliseconds");
+  }
+  return value;
+}
+
+export type InboundTriggerPolicy = "always" | "replies" | "never";
+
+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;
+
+  /** Controls whether inbound broker messages may automatically trigger a model turn */
+  inboundTrigger: InboundTriggerPolicy;
+
+  /** 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;
+
+  /** Expose the deprecated monolithic `intercom` tool to models (default: false) */
+  legacyTool: boolean;
+}
+
+export function getConfigPath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "config.json");
+}
+
+const defaults: IntercomConfig = {
+  brokerCommand: "npx",
+  brokerArgs: ["--no-install", "tsx"],
+  confirmSend: false,
+  inboundTrigger: "always",
+  enabled: true,
+  replyHint: true,
+  legacyTool: false,
+};
+
+function applyEnvironment(config: IntercomConfig): IntercomConfig {
+  const legacyToolEnv = process.env.PI_INTERCOM_LEGACY_TOOL?.trim().toLowerCase();
+  if (!legacyToolEnv) return config;
+  if (!["1", "true", "yes", "0", "false", "no"].includes(legacyToolEnv)) {
+    throw new Error("PI_INTERCOM_LEGACY_TOOL must be one of: 1, true, yes, 0, false, no");
+  }
+  config.legacyTool = ["1", "true", "yes"].includes(legacyToolEnv);
+  return config;
+}
+
+export function loadConfig(): IntercomConfig {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    try {
+      return applyEnvironment({ ...defaults });
+    } catch (error) {
+      console.error(`Failed to load intercom config at ${configPath}:`, error);
+      return { ...defaults, inboundTrigger: "never" };
+    }
+  }
+
+  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, "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, "inboundTrigger")) {
+      if (
+        parsedConfig.inboundTrigger !== "always"
+        && parsedConfig.inboundTrigger !== "replies"
+        && parsedConfig.inboundTrigger !== "never"
+      ) {
+        throw new Error(`"inboundTrigger" must be "always", "replies", or "never"`);
+      }
+      config.inboundTrigger = parsedConfig.inboundTrigger;
+    }
+
+    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, "legacyTool")) {
+      if (typeof parsedConfig.legacyTool !== "boolean") {
+        throw new Error(`"legacyTool" must be a boolean`);
+      }
+      config.legacyTool = parsedConfig.legacyTool;
+    }
+
+    if (Object.hasOwn(parsedConfig, "status")) {
+      if (typeof parsedConfig.status !== "string") {
+        throw new Error(`"status" must be a string`);
+      }
+      config.status = parsedConfig.status;
+    }
+
+    return applyEnvironment(config);
+  } catch (error) {
+    console.error(`Failed to load intercom config at ${configPath}:`, error);
+    return { ...defaults, inboundTrigger: "never" };
+  }
+}