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

package/broker/framing.ts

@@ -0,0 +1,87 @@
+import type { Socket } from "net";
+
+export const MAX_FRAME_BYTES = 1024 * 1024;
+
+/**
+ * Write a length-prefixed message to a socket.
+ * Format: 4-byte big-endian length + JSON payload
+ */
+export function writeMessage(socket: Socket, msg: unknown): void {
+  const json = JSON.stringify(msg);
+  const payload = Buffer.from(json, "utf-8");
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(payload.length, 0);
+  socket.write(Buffer.concat([header, payload]));
+}
+
+/**
+ * Create a message reader that handles partial reads.
+ * Calls onMessage for each complete message received.
+ * Protocol or handler errors are reported to onError so the caller can close the socket.
+ */
+export function createMessageReader(
+  onMessage: (msg: unknown) => void,
+  onError: (error: Error) => void,
+  maxFrameBytes = MAX_FRAME_BYTES,
+) {
+  let buffer = Buffer.alloc(0);
+
+  function reportMessage(payload: Buffer): boolean {
+    let msg: unknown;
+    try {
+      msg = JSON.parse(payload.toString("utf-8"));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onError(new Error(`Failed to parse intercom message: ${message}`, { cause: error }));
+      return false;
+    }
+
+    try {
+      onMessage(msg);
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
+      return false;
+    }
+  }
+
+  return (data: Buffer) => {
+    let remaining = data;
+
+    while (remaining.length > 0) {
+      if (buffer.length < 4) {
+        const headerBytes = Math.min(4 - buffer.length, remaining.length);
+        buffer = Buffer.concat([buffer, remaining.subarray(0, headerBytes)]);
+        remaining = remaining.subarray(headerBytes);
+        if (buffer.length < 4) {
+          return;
+        }
+      }
+
+      const length = buffer.readUInt32BE(0);
+      if (length > maxFrameBytes) {
+        buffer = Buffer.alloc(0);
+        onError(new Error(`Intercom frame length ${length} exceeds maximum ${maxFrameBytes} bytes`));
+        return;
+      }
+
+      const missingPayloadBytes = length - Math.max(0, buffer.length - 4);
+      const payloadBytes = Math.min(missingPayloadBytes, remaining.length);
+      if (payloadBytes > 0) {
+        buffer = Buffer.concat([buffer, remaining.subarray(0, payloadBytes)]);
+        remaining = remaining.subarray(payloadBytes);
+      }
+
+      if (buffer.length < 4 + length) {
+        return;
+      }
+
+      const payload = buffer.subarray(4, 4 + length);
+      buffer = Buffer.alloc(0);
+      if (!reportMessage(payload)) {
+        return;
+      }
+    }
+  };
+}

package/broker/ownership.ts

@@ -0,0 +1,61 @@
+import { closeSync, constants, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { INTERCOM_RUNTIME_FILE_MODE, restrictIntercomRuntimeFile } from "./paths.ts";
+
+function ownerPid(path: string): number | null {
+  try {
+    const pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function pidIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+export function acquireBrokerOwnership(path: string, pid = process.pid): void {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, INTERCOM_RUNTIME_FILE_MODE);
+      try {
+        writeFileSync(fd, String(pid));
+      } finally {
+        closeSync(fd);
+      }
+      restrictIntercomRuntimeFile(path);
+      return;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const existingPid = ownerPid(path);
+      if (existingPid !== null && pidIsAlive(existingPid)) {
+        throw new Error(`Intercom broker already owned by live process ${existingPid}`);
+      }
+      try {
+        unlinkSync(path);
+      } catch (unlinkError) {
+        if ((unlinkError as NodeJS.ErrnoException).code !== "ENOENT") throw unlinkError;
+      }
+    }
+  }
+  throw new Error("Could not acquire intercom broker ownership");
+}
+
+export function releaseBrokerOwnership(path: string, pid = process.pid): void {
+  if (ownerPid(path) !== pid) return;
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+export function hasBrokerOwnership(path: string, pid = process.pid): boolean {
+  return ownerPid(path) === pid;
+}
+

package/broker/paths.ts

@@ -0,0 +1,161 @@
+import { chmodSync, mkdirSync, readFileSync } from "fs";
+import { isAbsolute, join, resolve } from "path";
+import { homedir } from "os";
+
+export const INTERCOM_DIR_MODE = 0o700;
+export const INTERCOM_RUNTIME_FILE_MODE = 0o600;
+export const INTERCOM_TCP_HOST = "127.0.0.1";
+export const INTERCOM_PROTOCOL_NAME = "pi-intercom";
+export const INTERCOM_PROTOCOL_VERSION = 4;
+
+export interface BrokerTcpEndpoint {
+  transport: "tcp";
+  host: string;
+  port: number;
+  stateId?: string;
+}
+
+export type BrokerConnectTarget = string | BrokerTcpEndpoint;
+
+function sanitizePipeSegment(value: string): string {
+  return value
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase() || "default";
+}
+
+export function getAgentDirPath(
+  env: NodeJS.ProcessEnv = process.env,
+  homeDir: string = homedir(),
+  cwd: string = process.cwd(),
+): string {
+  const configured = env.PI_CODING_AGENT_DIR?.trim();
+  if (!configured) {
+    return join(homeDir, ".pi/agent");
+  }
+
+  return isAbsolute(configured) ? configured : resolve(cwd, configured);
+}
+
+export function getIntercomDirPath(agentDir: string = getAgentDirPath()): string {
+  return join(agentDir, "intercom");
+}
+
+export function shouldUseWindowsTcpTransport(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (platform !== "win32") {
+    return false;
+  }
+
+  const transport = env.PI_INTERCOM_TRANSPORT?.trim().toLowerCase();
+  if (transport === "tcp") {
+    return true;
+  }
+
+  const legacyOptIn = env.PI_INTERCOM_TCP?.trim().toLowerCase();
+  return legacyOptIn === "1" || legacyOptIn === "true";
+}
+
+export function getBrokerPortFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker.port.json");
+}
+
+export function getBrokerAskStateFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-asks.json");
+}
+
+export function getBrokerAccessStateFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-access.json");
+}
+
+export function getBrokerAdminCredentialFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-admin.json");
+}
+
+export function getBrokerAuditFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker-audit.jsonl");
+}
+
+export function getRemoteGatewaySocketPath(
+  platform: NodeJS.Platform = process.platform,
+  agentDir: string = getAgentDirPath(),
+): string {
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\pi-intercom-remote-${sanitizePipeSegment(agentDir)}`;
+  }
+  return join(getIntercomDirPath(agentDir), "remote-gateway.sock");
+}
+
+export function getBrokerSocketPath(
+  platform: NodeJS.Platform = process.platform,
+  agentDir: string = getAgentDirPath(),
+): string {
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\pi-intercom-${sanitizePipeSegment(agentDir)}`;
+  }
+
+  return join(getIntercomDirPath(agentDir), "broker.sock");
+}
+
+export function getBrokerConnectTarget(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+  intercomDir: string = getIntercomDirPath(getAgentDirPath(env)),
+): BrokerConnectTarget {
+  if (shouldUseWindowsTcpTransport(platform, env)) {
+    const endpointFile = getBrokerPortFilePath(intercomDir);
+    const raw = readFileSync(endpointFile, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`Invalid intercom TCP endpoint at ${endpointFile}: expected a JSON object`);
+    }
+    const endpoint = parsed as Record<string, unknown>;
+    if (
+      endpoint.transport !== "tcp"
+      || endpoint.host !== INTERCOM_TCP_HOST
+      || typeof endpoint.port !== "number"
+      || !Number.isSafeInteger(endpoint.port)
+      || endpoint.port <= 0
+      || endpoint.port > 65535
+      || typeof endpoint.stateId !== "string"
+      || endpoint.stateId.length === 0
+    ) {
+      throw new Error(`Invalid intercom TCP endpoint at ${endpointFile}`);
+    }
+    return { transport: "tcp", host: endpoint.host, port: endpoint.port, stateId: endpoint.stateId };
+  }
+
+  return getBrokerSocketPath(platform, getAgentDirPath(env));
+}
+
+export function getBrokerListenTarget(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): BrokerConnectTarget {
+  if (shouldUseWindowsTcpTransport(platform, env)) {
+    return { transport: "tcp", host: INTERCOM_TCP_HOST, port: 0 };
+  }
+
+  return getBrokerSocketPath(platform, getAgentDirPath(env));
+}
+
+export function ensureIntercomRuntimeDir(
+  intercomDir: string = getIntercomDirPath(),
+  platform: NodeJS.Platform = process.platform,
+): void {
+  mkdirSync(intercomDir, { recursive: true, mode: INTERCOM_DIR_MODE });
+  if (platform !== "win32") {
+    chmodSync(intercomDir, INTERCOM_DIR_MODE);
+  }
+}
+
+export function restrictIntercomRuntimeFile(
+  filePath: string,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  if (platform !== "win32") {
+    chmodSync(filePath, INTERCOM_RUNTIME_FILE_MODE);
+  }
+}