@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

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

@@ -0,0 +1,558 @@
+import { EventEmitter } from "events";
+import net from "net";
+import { randomUUID } from "crypto";
+import { writeMessage, createMessageReader } from "./framing.ts";
+import { getBrokerSocketPath, getLegacyBrokerSocketPath, isOwnedBrokerSocket } from "./paths.ts";
+import { compactTopicMessage, normalizeMessage, normalizeSessionInfo } from "../types.ts";
+import type { SessionInfo, Message, Attachment, MessageDelivery, QueueMode, HumanMessageOrigin, TopicUpdate, TopicChange, SessionSnapshot, SendResult } from "../types.ts";
+export type { SendResult } from "../types.ts";
+
+/** Default delivery-ack timeout for `send` (broker acknowledges quickly). */
+const DEFAULT_SEND_TIMEOUT_MS = 8000;
+/** Default timeout for `listSessions` responses. */
+const DEFAULT_LIST_TIMEOUT_MS = 5000;
+
+export interface IntercomClientOptions {
+  /** Timeout (ms) for the broker to acknowledge message delivery. */
+  sendTimeoutMs?: number;
+  /** Timeout (ms) for a session list response. */
+  listTimeoutMs?: number;
+}
+
+interface SendOptions {
+  text: string;
+  attachments?: Attachment[];
+  replyTo?: string;
+  expectsReply?: boolean;
+  delivery?: MessageDelivery;
+  queueMode?: QueueMode;
+  threadId?: string;
+  passive?: boolean;
+  messageId?: string;
+  human?: HumanMessageOrigin;
+  topic?: TopicUpdate;
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function connectSocket(socketPath: string, timeoutMs = 500): Promise<net.Socket> {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(socketPath);
+    const finish = (error?: Error) => {
+      clearTimeout(timeout);
+      socket.off("connect", onConnect);
+      socket.off("error", onError);
+      if (error) {
+        socket.destroy();
+        reject(error);
+      } else {
+        resolve(socket);
+      }
+    };
+    const onConnect = () => finish();
+    const onError = (error: Error) => finish(error);
+    socket.once("connect", onConnect);
+    socket.once("error", onError);
+    const timeout = setTimeout(() => finish(new Error(`Connection timeout: ${socketPath}`)), timeoutMs);
+    timeout.unref?.();
+  });
+}
+
+async function connectBrokerSocket(): Promise<net.Socket> {
+  const preferred = getBrokerSocketPath();
+  const legacy = getLegacyBrokerSocketPath();
+  const candidates = [preferred, ...(legacy !== preferred ? [legacy] : [])];
+  let lastError: Error | undefined;
+  for (const candidate of candidates) {
+    if (!isOwnedBrokerSocket(candidate)) continue;
+    try {
+      return await connectSocket(candidate);
+    } catch (error) {
+      lastError = toError(error);
+    }
+  }
+  throw lastError ?? new Error(`Intercom broker socket is unavailable: ${preferred}`);
+}
+
+export class IntercomClient extends EventEmitter {
+  private socket: net.Socket | null = null;
+  private _sessionId: string | null = null;
+  private _topicsSupported = false;
+  private pendingSends = new Map<string, { resolve: (r: SendResult) => void; reject: (e: Error) => void }>();
+  private pendingLists = new Map<string, { resolve: (snapshot: SessionSnapshot) => void; reject: (e: Error) => void; sessions: Map<string, SessionInfo>; receipts: SessionSnapshot["receipts"] }>();
+  private connecting = false;
+  private disconnecting = false;
+  private disconnectError: Error | null = null;
+  private readonly sendTimeoutMs: number;
+  private readonly listTimeoutMs: number;
+
+  constructor(options: IntercomClientOptions = {}) {
+    super();
+    this.sendTimeoutMs = options.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS;
+    this.listTimeoutMs = options.listTimeoutMs ?? DEFAULT_LIST_TIMEOUT_MS;
+  }
+
+  private failPending(error: Error): void {
+    for (const pending of this.pendingSends.values()) {
+      pending.reject(error);
+    }
+    this.pendingSends.clear();
+    for (const pending of this.pendingLists.values()) {
+      pending.reject(error);
+    }
+    this.pendingLists.clear();
+  }
+
+  get sessionId(): string | null {
+    return this._sessionId;
+  }
+
+  get supportsTopics(): boolean { return this.isConnected() && this._topicsSupported; }
+  isConnected(): boolean {
+    const socket = this.socket;
+    return Boolean(socket && this._sessionId && !this.disconnecting && !socket.destroyed && !socket.writableEnded && socket.writable);
+  }
+
+  private requireActiveSocket(): net.Socket {
+    if (this.disconnecting) {
+      throw new Error("Client disconnecting");
+    }
+
+    const socket = this.socket;
+    if (!socket || !this._sessionId) {
+      throw new Error("Not connected");
+    }
+
+    if (socket.destroyed || socket.writableEnded || !socket.writable) {
+      throw new Error("Client disconnected");
+    }
+
+    return socket;
+  }
+
+  async connect(session: Omit<SessionInfo, "id">, requestedId?: string): Promise<void> {
+    if (this.socket || this.connecting) {
+      throw new Error("Already connected");
+    }
+
+    this.connecting = true;
+    let socket: net.Socket;
+    try {
+      socket = await connectBrokerSocket();
+    } finally {
+      this.connecting = false;
+    }
+    const { topics, subscriptions, ...identity } = session;
+    await new Promise<void>((resolve, reject) => {
+      this.socket = socket;
+      this.disconnectError = null;
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (!this._sessionId) {
+          cleanupConnectionAttempt();
+          cleanupSocketListeners();
+          if (this.socket === socket) {
+            this.socket = null;
+          }
+          socket.destroy();
+          reject(new Error("Connection timeout"));
+        }
+      }, 10000);
+      timeout.unref?.();
+
+      let connectionEstablished = false;
+
+      const onRegistered = () => {
+        settled = true;
+        connectionEstablished = true;
+        cleanupConnectionAttempt();
+        resolve();
+      };
+
+      const onError = (err: Error) => {
+        settled = true;
+        cleanupConnectionAttempt();
+        cleanupSocketListeners();
+        if (this.socket === socket) {
+          this.socket = null;
+        }
+        socket.destroy();
+        reject(err);
+      };
+
+      const onClose = () => {
+        const wasConnecting = !settled && !this._sessionId;
+        const wasDisconnecting = this.disconnecting;
+        const disconnectError = this.disconnectError ?? new Error("Client disconnected");
+        this.disconnecting = false;
+        cleanupConnectionAttempt();
+        cleanupSocketListeners();
+        this.failPending(disconnectError);
+        if (this.socket === socket) {
+          this.socket = null;
+        }
+        this._sessionId = null;
+        this.disconnectError = null;
+        if (connectionEstablished && !wasDisconnecting) {
+          this.emit("disconnected", disconnectError);
+        }
+        if (wasConnecting) {
+          reject(new Error("Connection closed before registration"));
+        }
+      };
+
+      const onSocketError = (err: Error) => {
+        if (connectionEstablished) {
+          this.disconnectError = err;
+          this.emit("error", err);
+        }
+      };
+
+      const onReaderError = (error: Error) => {
+        const protocolError = new Error(`Intercom protocol error: ${error.message}`, { cause: error });
+        if (!connectionEstablished) {
+          onError(protocolError);
+          return;
+        }
+        this.disconnectError = protocolError;
+        this.emit("error", protocolError);
+        socket.destroy();
+      };
+
+      const reader = createMessageReader((msg) => {
+        this.handleBrokerMessage(msg);
+      }, onReaderError);
+
+      const cleanupConnectionAttempt = () => {
+        this.off("_registered", onRegistered);
+        socket.off("error", onError);
+        clearTimeout(timeout);
+      };
+
+      const cleanupSocketListeners = () => {
+        socket.off("data", reader);
+        socket.off("error", onSocketError);
+        socket.off("close", onClose);
+      };
+
+      socket.on("data", reader);
+      socket.on("error", onError);
+      socket.on("close", onClose);
+
+      socket.on("error", onSocketError);
+      this.once("_registered", onRegistered);
+
+      try {
+        writeMessage(socket, { type: "register", session: identity, requestedId, topicFrames: true });
+      } catch (error) {
+        cleanupConnectionAttempt();
+        cleanupSocketListeners();
+        if (this.socket === socket) {
+          this.socket = null;
+        }
+        socket.destroy();
+        reject(toError(error));
+      }
+    });
+    if (this.supportsTopics) {
+      for (const topic of topics ?? []) await this.updateTopics({ action: "restore", topic });
+      for (const subscription of subscriptions ?? []) await this.updateTopics({ action: "restore", subscription });
+    }
+  }
+
+  private handleBrokerMessage(msg: unknown): void {
+    if (typeof msg !== "object" || msg === null || !("type" in msg) || typeof msg.type !== "string") {
+      throw new Error("Invalid broker message");
+    }
+
+    const brokerMessage = msg as { type: string } & Record<string, unknown>;
+
+    if (this._sessionId === null && brokerMessage.type !== "registered") {
+      throw new Error(`Received ${brokerMessage.type} before registered`);
+    }
+
+    switch (brokerMessage.type) {
+      case "registered": {
+        if (typeof brokerMessage.sessionId !== "string") {
+          throw new Error("Invalid registered message");
+        }
+
+        if (this._sessionId !== null) {
+          throw new Error("Received duplicate registered message");
+        }
+
+        this._sessionId = brokerMessage.sessionId;
+        this._topicsSupported = brokerMessage.topicsSupported === true && brokerMessage.topicFrames === true;
+        this.emit("_registered", { type: "registered", sessionId: brokerMessage.sessionId });
+        break;
+      }
+
+      case "sessions": {
+        const { requestId, sessions, receipts, more, error } = brokerMessage;
+        if (typeof requestId !== "string" || !Array.isArray(sessions) || (more !== undefined && typeof more !== "boolean")) throw new Error("Invalid sessions message");
+        const pending = this.pendingLists.get(requestId);
+        if (!pending) return;
+        if (typeof error === "string") {
+          this.pendingLists.delete(requestId);
+          pending.reject(new Error(error));
+          break;
+        }
+        for (const row of sessions) {
+          if (!row || typeof row.id !== "string" || (row.topics !== undefined && !Array.isArray(row.topics)) || (row.subscriptions !== undefined && !Array.isArray(row.subscriptions))) throw new Error("Invalid session snapshot row");
+          const previous = pending.sessions.get(row.id);
+          const info = normalizeSessionInfo({ ...previous, ...row,
+            ...(row.topics ? { topics: [...(previous?.topics ?? []), ...row.topics] } : {}),
+            ...(row.subscriptions ? { subscriptions: [...(previous?.subscriptions ?? []), ...row.subscriptions] } : {}),
+          });
+          if (!info) throw new Error("Invalid session snapshot");
+          pending.sessions.set(info.id, info);
+        }
+        if (receipts !== undefined) {
+          if (!Array.isArray(receipts) || receipts.some((receipt) => !receipt || typeof receipt.to !== "string" || typeof receipt.id !== "string" || typeof receipt.accepted !== "boolean" || typeof receipt.delivered !== "boolean")) throw new Error("Invalid topic delivery receipts");
+          pending.receipts.push(...receipts);
+        }
+        if (more !== true) {
+          this.pendingLists.delete(requestId);
+          pending.resolve({ sessions: [...pending.sessions.values()], receipts: pending.receipts });
+        }
+        break;
+      }
+
+      case "message": {
+        const { from } = brokerMessage;
+        const message = normalizeMessage(brokerMessage.message);
+        const normalizedFrom = normalizeSessionInfo(from);
+        if (!normalizedFrom || !message) {
+          throw new Error("Invalid message event");
+        }
+
+        this.emit("message", normalizedFrom, message);
+        break;
+      }
+
+      case "delivered": {
+        const { messageId } = brokerMessage;
+        if (typeof messageId !== "string") {
+          throw new Error("Invalid delivered message");
+        }
+
+        const pending = this.pendingSends.get(messageId);
+        if (!pending) {
+          // Late send responses are harmless once the caller has already timed out.
+          return;
+        }
+
+        this.pendingSends.delete(messageId);
+        pending.resolve({ id: messageId, accepted: true, delivered: true });
+        break;
+      }
+
+      case "delivery_queued": {
+        const { messageId, reason } = brokerMessage;
+        if (typeof messageId !== "string" || typeof reason !== "string") {
+          throw new Error("Invalid delivery_queued message");
+        }
+
+        const pending = this.pendingSends.get(messageId);
+        if (!pending) {
+          // Late send responses are harmless once the caller has already timed out.
+          return;
+        }
+
+        this.pendingSends.delete(messageId);
+        pending.resolve({ id: messageId, accepted: true, delivered: false, queued: true, reason });
+        break;
+      }
+
+      case "delivery_failed": {
+        const { messageId, reason } = brokerMessage;
+        if (typeof messageId !== "string" || typeof reason !== "string") {
+          throw new Error("Invalid delivery_failed message");
+        }
+
+        const pending = this.pendingSends.get(messageId);
+        if (!pending) {
+          // Late send responses are harmless once the caller has already timed out.
+          return;
+        }
+
+        this.pendingSends.delete(messageId);
+        pending.resolve({ id: messageId, accepted: false, delivered: false, reason });
+        break;
+      }
+
+      case "session_left": {
+        if (typeof brokerMessage.sessionId !== "string") {
+          throw new Error("Invalid session_left message");
+        }
+
+        this.emit("session_left", brokerMessage.sessionId);
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown broker message type: ${brokerMessage.type}`);
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    const socket = this.socket;
+    if (!socket) {
+      return;
+    }
+
+    this.disconnecting = true;
+    this.disconnectError = null;
+    this.failPending(new Error("Client disconnected"));
+
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        socket.off("close", onClose);
+        socket.off("error", onError);
+        resolve();
+      };
+      const onClose = () => finish();
+      const onError = () => {
+        socket.destroy();
+      };
+      const timeout = setTimeout(() => {
+        socket.destroy();
+      }, 2000);
+
+      socket.once("close", onClose);
+      socket.once("error", onError);
+
+      try {
+        writeMessage(socket, { type: "unregister" });
+        socket.end();
+      } catch {
+        // Disconnect should still finish even if the unregister write fails.
+        socket.destroy();
+      }
+    });
+  }
+
+  listSessions(): Promise<SessionInfo[]> {
+    return this.requestSessions().then((snapshot) => snapshot.sessions);
+  }
+
+  updateTopics(change: TopicChange, onAccepted?: (snapshot: SessionSnapshot) => void): Promise<SessionSnapshot> {
+    if (!this.supportsTopics) return Promise.reject(new Error("This broker does not support topic snapshots."));
+    return this.requestSessions(change, onAccepted);
+  }
+
+  private requestSessions(change?: TopicChange, onAccepted?: (snapshot: SessionSnapshot) => void): Promise<SessionSnapshot> {
+    let socket: net.Socket;
+    try {
+      socket = this.requireActiveSocket();
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+
+    return new Promise((resolve, reject) => {
+      const requestId = randomUUID();
+      const wrappedResolve = (snapshot: SessionSnapshot) => {
+        clearTimeout(timeout);
+        try {
+          // Commit confirmed subscriptions before handling a following message in the same read.
+          onAccepted?.(snapshot);
+          resolve(snapshot);
+        } catch (error) { reject(toError(error)); }
+      };
+      const wrappedReject = (error: Error) => {
+        clearTimeout(timeout);
+        reject(error);
+      };
+      const timeout = setTimeout(() => {
+        if (this.pendingLists.has(requestId)) {
+          this.pendingLists.delete(requestId);
+          wrappedReject(new Error("List sessions timeout"));
+        }
+      }, this.listTimeoutMs);
+      timeout.unref?.();
+      this.pendingLists.set(requestId, { resolve: wrappedResolve, reject: wrappedReject, sessions: new Map(), receipts: [] });
+      try {
+        writeMessage(socket, { type: "list", requestId, stream: true, ...(change ? { change } : {}) });
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingLists.delete(requestId);
+        reject(toError(error));
+      }
+    });
+  }
+
+  send(to: string, options: SendOptions): Promise<SendResult> {
+    let socket: net.Socket;
+    try {
+      socket = this.requireActiveSocket();
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+
+    const messageId = options.messageId ?? randomUUID();
+    const message: Message = {
+      id: messageId,
+      timestamp: Date.now(),
+      replyTo: options.replyTo,
+      expectsReply: options.expectsReply,
+      ...(options.human ? { human: options.human } : {}),
+      ...(options.topic ? { topic: options.topic } : {}),
+      delivery: options.delivery ?? (options.passive === true ? "passive" : options.expectsReply === true ? undefined : "steer"),
+      queueMode: options.queueMode,
+      threadId: options.threadId,
+      passive: options.passive,
+      content: {
+        text: options.text,
+        attachments: options.attachments,
+      },
+    };
+
+    return new Promise((resolve, reject) => {
+      const wrappedResolve = (result: SendResult) => {
+        clearTimeout(timeout);
+        resolve(result);
+      };
+      const wrappedReject = (error: Error) => {
+        clearTimeout(timeout);
+        reject(error);
+      };
+      const timeout = setTimeout(() => {
+        if (this.pendingSends.has(messageId)) {
+          this.pendingSends.delete(messageId);
+          wrappedReject(new Error("Send timeout"));
+        }
+      }, this.sendTimeoutMs);
+      timeout.unref?.();
+      this.pendingSends.set(messageId, { resolve: wrappedResolve, reject: wrappedReject });
+
+      try {
+        writeMessage(socket, { type: "send", to, message: this._topicsSupported ? compactTopicMessage(message) : message });
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingSends.delete(messageId);
+        reject(toError(error));
+      }
+    });
+  }
+
+  updatePresence(updates: { name?: string; status?: string; model?: string; pendingAsks?: number; acceptsAsks?: boolean; lastIntercomActivity?: number; subscriptions?: SessionInfo["subscriptions"]; topics?: TopicUpdate[] }): void {
+    if (this.disconnecting) {
+      return;
+    }
+
+    const socket = this.socket;
+    if (!socket || !this._sessionId || socket.destroyed || socket.writableEnded || !socket.writable) {
+      return;
+    }
+
+    writeMessage(socket, { type: "presence", ...updates });
+  }
+}

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

@@ -0,0 +1,77 @@
+import type { Socket } from "net";
+
+export const MAX_FRAME_SIZE_BYTES = 1024 * 1024;
+
+export function intercomMessageSizeBytes(msg: unknown): number {
+  return Buffer.byteLength(JSON.stringify(msg), "utf-8");
+}
+
+export function validateIntercomMessageSize(msg: unknown): Error | null {
+  const size = intercomMessageSizeBytes(msg);
+  return size > MAX_FRAME_SIZE_BYTES
+    ? new Error(`Intercom message too large (${size} bytes; max ${MAX_FRAME_SIZE_BYTES})`)
+    : null;
+}
+
+/**
+ * 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 tooLarge = validateIntercomMessageSize(msg);
+  if (tooLarge) throw tooLarge;
+  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,
+) {
+  let buffer = Buffer.alloc(0);
+
+  return (data: Buffer) => {
+    buffer = Buffer.concat([buffer, data]);
+
+    while (buffer.length >= 4) {
+      const length = buffer.readUInt32BE(0);
+      if (length > MAX_FRAME_SIZE_BYTES) {
+        onError(new Error(`Intercom frame too large (${length} bytes; max ${MAX_FRAME_SIZE_BYTES})`));
+        buffer = Buffer.alloc(0);
+        return;
+      }
+
+      if (buffer.length < 4 + length) {
+        break;
+      }
+
+      const payload = buffer.subarray(4, 4 + length);
+      buffer = buffer.subarray(4 + length);
+
+      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;
+      }
+
+      try {
+        onMessage(msg);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
+        return;
+      }
+    }
+  };
+}

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

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { getPiAgentDir } from "../agent-dir.ts";
+
+const MAX_UNIX_SOCKET_PATH_BYTES = 100;
+
+function agentDigest(agentDir: string, uid?: number): string {
+	return createHash("sha256").update(uid === undefined ? agentDir : `${uid}:${agentDir}`).digest("hex").slice(0, 16);
+}
+
+export function getLegacyBrokerSocketPath(agentDir: string = getPiAgentDir()): string {
+	return join(tmpdir(), `pi-intercom-${agentDigest(agentDir)}.sock`);
+}
+
+export function isOwnedBrokerSocket(socketPath: string): boolean {
+	try {
+		const stat = fs.lstatSync(socketPath);
+		const uid = process.getuid?.();
+		return stat.isSocket() && (uid === undefined || stat.uid === uid);
+	} catch {
+		return false;
+	}
+}
+
+export function getBrokerSocketPath(agentDir: string = getPiAgentDir()): string {
+	const uid = process.getuid?.();
+	const suffix = `pi-intercom-${agentDigest(agentDir, uid)}`;
+	const preferred = join(tmpdir(), suffix, "broker.sock");
+	return Buffer.byteLength(preferred) <= MAX_UNIX_SOCKET_PATH_BYTES
+		? preferred
+		: join("/tmp", suffix, "broker.sock");
+}
+
+export function prepareBrokerSocketPath(): string {
+	const socketPath = getBrokerSocketPath();
+	const brokerDir = dirname(socketPath);
+	fs.mkdirSync(brokerDir, { recursive: true, mode: 0o700 });
+	const stat = fs.lstatSync(brokerDir);
+	const uid = process.getuid?.();
+	if (!stat.isDirectory() || stat.isSymbolicLink() || (uid !== undefined && stat.uid !== uid)) {
+		throw new Error(`Unsafe intercom socket directory: ${brokerDir}`);
+	}
+	fs.chmodSync(brokerDir, 0o700);
+	return socketPath;
+}