@ctliz/agent-intercom-claude 0.12.0-connect.3

package/broker/spawn.ts

@@ -0,0 +1,463 @@
+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_HASH, POLICY_SEMANTICS_VERSION } from "@ctliz/agent-intercom-core";
+import { createMessageReader, writeMessage } from "./framing.ts";
+import { assertCompatibleOrdinaryAdvertisement } from "./boss-contracts.ts";
+import { hasExactDataKeys, isPlainDataRecord } from "./validation.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 getBrokerEntryPath(moduleUrl: string = import.meta.url): string {
+  const moduleDir = dirname(fileURLToPath(moduleUrl));
+  const bundledBroker = join(moduleDir, "broker.mjs");
+  return existsSync(bundledBroker) ? bundledBroker : join(moduleDir, "broker.ts");
+}
+
+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 (!hasExactDataKeys(
+    message,
+    ["type", "requestId", "protocol", "version", "endpoint", "remoteAccess"],
+    ["capabilities"],
+  )) return false;
+  const response = message;
+  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 (!hasExactDataKeys(remoteAccess, ["feature", "policySemanticsVersion", "policySemanticsHash"])) return false;
+  const contract = remoteAccess;
+  const legacyCompatible = contract.feature === "remote-access-v1"
+    && contract.policySemanticsVersion === POLICY_SEMANTICS_VERSION
+    && contract.policySemanticsHash === POLICY_SEMANTICS_HASH;
+  if (!legacyCompatible) return false;
+  if (response.capabilities !== undefined) {
+    try {
+      assertCompatibleOrdinaryAdvertisement(response.capabilities);
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+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 = getBrokerEntryPath();
+    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 (
+        isPlainDataRecord(message)
+        && message.type === "health_ok"
+        && 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/broker/validation.ts

@@ -0,0 +1,132 @@
+import { types as nodeUtilTypes } from "node:util";
+
+/** Reject accessors, inherited records, and Proxies before reading wire data. */
+export function isPlainDataRecord(value: unknown): value is Record<string, unknown> {
+  if (
+    typeof value !== "object"
+    || value === null
+    || nodeUtilTypes.isProxy(value)
+    || Array.isArray(value)
+    || Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    return false;
+  }
+  try {
+    return Reflect.ownKeys(value).every((key) => {
+      if (typeof key !== "string") return false;
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return descriptor !== undefined && descriptor.enumerable && Object.hasOwn(descriptor, "value");
+    });
+  } catch {
+    return false;
+  }
+}
+
+/** Require a plain record with exactly the declared own data properties. */
+export function hasExactDataKeys(
+  value: unknown,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): value is Record<string, unknown> {
+  if (!isPlainDataRecord(value)) return false;
+  const allowed = new Set([...required, ...optional]);
+  const keys = Reflect.ownKeys(value);
+  return keys.length >= required.length
+    && keys.every((key) => typeof key === "string" && allowed.has(key))
+    && required.every((key) => Object.hasOwn(value, key));
+}
+
+/**
+ * Preflight an authoritative nested graph without invoking Proxy traps or
+ * accessors. Core parsers may run only after this adapter-owned check passes.
+ */
+export function assertPlainDataGraph(value: unknown, path = "$", seen = new WeakSet<object>()): void {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) return;
+  if (nodeUtilTypes.isProxy(value)) {
+    throw new Error(`${path} must not contain a Proxy`);
+  }
+  if (seen.has(value)) {
+    throw new Error(`${path} must not contain a cycle or repeated object reference`);
+  }
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype) {
+      throw new Error(`${path} must use the exact Array prototype`);
+    }
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+    if (lengthDescriptor === undefined || !Object.hasOwn(lengthDescriptor, "value")) {
+      throw new Error(`${path}.length must be an own data property`);
+    }
+    const length = lengthDescriptor.value;
+    const descriptors = new Map<number, PropertyDescriptor>();
+    for (const key of Reflect.ownKeys(value)) {
+      if (key === "length") continue;
+      if (typeof key !== "string") throw new Error(`${path} must not contain symbol properties`);
+      const index = Number(key);
+      if (!Number.isInteger(index) || index < 0 || index >= length || String(index) !== key) {
+        throw new Error(`${path} must not contain non-index properties`);
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor === undefined || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+        throw new Error(`${path}[${index}] must be an enumerable own data property`);
+      }
+      descriptors.set(index, descriptor);
+    }
+    if (descriptors.size !== length) throw new Error(`${path} must be dense`);
+    for (let index = 0; index < length; index += 1) {
+      const descriptor = descriptors.get(index);
+      if (descriptor === undefined) throw new Error(`${path} must be dense`);
+      assertPlainDataGraph(descriptor.value, `${path}[${index}]`, seen);
+    }
+    return;
+  }
+
+  if (Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new Error(`${path} must be a plain data object`);
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string") throw new Error(`${path} must not contain symbol properties`);
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      throw new Error(`${path}.${key} must be an enumerable own data property`);
+    }
+    assertPlainDataGraph(descriptor.value, `${path}.${key}`, seen);
+  }
+}
+
+/** Array.prototype.every skips holes; wire arrays must instead be exact and dense. */
+export function isDenseArrayOf<T>(
+  value: unknown,
+  predicate: (entry: unknown, index: number) => entry is T,
+): value is T[] {
+  if (
+    typeof value !== "object"
+    || value === null
+    || nodeUtilTypes.isProxy(value)
+    || !Array.isArray(value)
+    || Object.getPrototypeOf(value) !== Array.prototype
+  ) return false;
+  try {
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+    if (lengthDescriptor === undefined || !Object.hasOwn(lengthDescriptor, "value")) return false;
+    const length = lengthDescriptor.value;
+    const entries = new Map<number, unknown>();
+    for (const key of Reflect.ownKeys(value)) {
+      if (key === "length") continue;
+      if (typeof key !== "string") return false;
+      const index = Number(key);
+      if (!Number.isInteger(index) || index < 0 || index >= length || String(index) !== key) return false;
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor === undefined || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) return false;
+      entries.set(index, descriptor.value);
+    }
+    if (entries.size !== length) return false;
+    for (let index = 0; index < length; index += 1) {
+      if (!predicate(entries.get(index), index)) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}