@fitchmultz/pi-subagents 0.49.1 → 0.51.0

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

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { getPiAgentDir } from "../agent-dir.ts";
 
 const MAX_UNIX_SOCKET_PATH_BYTES = 100;
@@ -13,8 +13,17 @@ function agentDigest(agentDir: string, uid?: number): string {
     .slice(0, 16);
 }
 
-export function getLegacyBrokerSocketPath(agentDir: string = getPiAgentDir()): string {
-  return join(tmpdir(), `pi-intercom-${agentDigest(agentDir)}.sock`);
+/** Old agent-directory namespaces are inspected for migration, never used for routing. */
+export function getPreviousBrokerSocketPaths(): readonly string[] {
+  const agentDir = getPiAgentDir();
+  const suffix = `pi-intercom-${agentDigest(agentDir, process.getuid?.())}`;
+  const preferred = join(tmpdir(), suffix, "broker.sock");
+  return [
+    Buffer.byteLength(preferred) <= MAX_UNIX_SOCKET_PATH_BYTES
+      ? preferred
+      : join("/tmp", suffix, "broker.sock"),
+    join(tmpdir(), `pi-intercom-${agentDigest(agentDir)}.sock`),
+  ];
 }
 
 export function isOwnedBrokerSocket(socketPath: string): boolean {
@@ -27,24 +36,64 @@ export function isOwnedBrokerSocket(socketPath: string): boolean {
   }
 }
 
-export function getBrokerSocketPath(agentDir: string = getPiAgentDir()): string {
+function defaultRuntimeRoot(): string {
+  if (process.platform !== "android") {
+    return "/tmp";
+  }
+  return process.env.PREFIX === undefined ? tmpdir() : join(process.env.PREFIX, "tmp");
+}
+
+function runtimeDirectory(socketName: string, sibling = ""): string {
+  const configured = process.env.PI_INTERCOM_RUNTIME_DIR;
   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");
+  if (uid === undefined) {
+    throw new Error("Intercom requires Unix user IDs and Unix domain sockets.");
+  }
+  const base = configured ?? join(defaultRuntimeRoot(), `pi-intercom-${uid}`);
+  const directory = isAbsolute(base) && sibling !== "" ? `${resolve(base)}${sibling}` : base;
+  if (
+    !isAbsolute(directory) ||
+    directory.includes("\0") ||
+    Buffer.byteLength(join(directory, socketName)) > MAX_UNIX_SOCKET_PATH_BYTES
+  ) {
+    throw new Error("PI_INTERCOM_RUNTIME_DIR must be an absolute short Unix socket directory.");
+  }
+  return directory;
 }
 
-export function prepareBrokerSocketPath(): string {
-  const socketPath = getBrokerSocketPath();
-  const brokerDir = dirname(socketPath);
-  fs.mkdirSync(brokerDir, { recursive: true, mode: 0o700 });
-  const stat = fs.lstatSync(brokerDir);
+/** A deployment can explicitly opt out of same-user discovery with a private runtime directory. */
+export function getBrokerRuntimeDir(): string {
+  return runtimeDirectory("broker.sock");
+}
+
+/** Read-only child observation endpoints share the runtime policy, not the broker namespace.
+ * The endpoint name is a short token digest because the private runtime directory also counts
+ * toward the Unix-socket path limit; a full token made nested test/deployment roots overflow. */
+export function agentObservationSocketPath(token: string): string {
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(token)) {
+    throw new Error("Invalid actor token.");
+  }
+  const name = `obs-${createHash("sha256").update(token).digest("hex").slice(0, 16)}.sock`;
+  return join(runtimeDirectory(name, "-agents"), name);
+}
+
+export function getBrokerSocketPath(): string {
+  return join(getBrokerRuntimeDir(), "broker.sock");
+}
+
+/** Create or verify an owned, non-symlink, private socket directory. */
+export function preparePrivateSocketPath(socketPath: string): string {
+  const directory = dirname(socketPath);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(directory);
   const uid = process.getuid?.();
   if (!stat.isDirectory() || stat.isSymbolicLink() || (uid !== undefined && stat.uid !== uid)) {
-    throw new Error(`Unsafe intercom socket directory: ${brokerDir}`);
+    throw new Error(`Unsafe intercom socket directory: ${directory}`);
   }
-  fs.chmodSync(brokerDir, 0o700);
+  fs.chmodSync(directory, 0o700);
   return socketPath;
 }
+
+export function prepareBrokerSocketPath(): string {
+  return preparePrivateSocketPath(getBrokerSocketPath());
+}

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

@@ -80,6 +80,11 @@ export function brokerPidRecord(): string {
 }
 
 export function isBrokerPidReused(pid: number, record: string): boolean {
+  return isLinuxProcessReplaced(pid, record.slice(record.indexOf("\n") + 1));
+}
+
+/** True only when a live Linux PID provably names a different process than the identity. */
+export function isLinuxProcessReplaced(pid: number, identity: string): boolean {
   const current = readLinuxProcess(pid);
   if (!current) {
     return false;
@@ -87,7 +92,7 @@ export function isBrokerPidReused(pid: number, record: string): boolean {
   if (current.tgid !== pid) {
     return true;
   }
-  const saved = IDENTITY.exec(record.slice(record.indexOf("\n") + 1).trim());
+  const saved = IDENTITY.exec(identity.trim());
   const actual = IDENTITY.exec(current.identity ?? "");
   if (!saved || !actual) {
     return false;

package/src/pi-intercom/broker/server-connection.ts

@@ -0,0 +1,63 @@
+import type net from "node:net";
+import { randomUUID } from "node:crypto";
+import { createMessageReader } from "./framing.ts";
+import { assertMainParent } from "./targets.ts";
+import { isSessionRegistration, type SessionInfo } from "../types.ts";
+import type { UnknownRecord } from "../../shared/unknown.ts";
+
+export function registeredSessionInfo(
+  msg: UnknownRecord,
+  sessions: ReadonlyMap<string, { readonly info: SessionInfo }>,
+): SessionInfo {
+  if (!isSessionRegistration(msg.session)) {
+    throw new Error("Invalid register message");
+  }
+  assertMainParent(msg.session, sessions);
+  const requestedId =
+    typeof msg.requestedId === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(msg.requestedId)
+      ? msg.requestedId
+      : undefined;
+  const id = requestedId !== undefined && !sessions.has(requestedId) ? requestedId : randomUUID();
+  return {
+    ...msg.session,
+    id,
+    guardedDelivery: msg.guardedDelivery === 1 ? msg.session.guardedDelivery : undefined,
+    lastSeen: msg.session.lastSeen ?? Date.now(),
+  };
+}
+
+type ClientMessageHandler = (
+  socket: net.Socket,
+  message: unknown,
+  sessionId: string | null,
+  registered: (id: string | null) => void,
+) => void;
+
+/** A server connection owns its registration identity until the socket closes. */
+export function acceptBrokerConnection(
+  socket: net.Socket,
+  handleMessage: ClientMessageHandler,
+  disconnected: (sessionId: string) => void,
+): void {
+  let sessionId: string | null = null;
+  socket.on(
+    "data",
+    createMessageReader(
+      (message) =>
+        handleMessage(socket, message, sessionId, (id) => {
+          sessionId = id;
+        }),
+      (error) => {
+        socket.destroy(error);
+      },
+    ),
+  );
+  socket.on("close", () => {
+    if (sessionId !== null) {
+      disconnected(sessionId);
+    }
+  });
+  socket.on("error", (error: Error) => {
+    console.error("Socket error:", error);
+  });
+}

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

@@ -1,18 +1,22 @@
 import { spawn } from "child_process";
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { mkdir } from "fs/promises";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import net from "net";
 import { getPiAgentDir } from "../agent-dir.ts";
-import { getBrokerSocketPath, getLegacyBrokerSocketPath, isOwnedBrokerSocket } from "./paths.ts";
+import {
+  getBrokerRuntimeDir,
+  getBrokerSocketPath,
+  getPreviousBrokerSocketPaths,
+  isOwnedBrokerSocket,
+  prepareBrokerSocketPath,
+} from "./paths.ts";
 import { isBrokerPidReused } from "./pid.ts";
 import { errorMessage, hasErrorCode } from "../../shared/unknown.ts";
 
-const INTERCOM_DIR = join(getPiAgentDir(), "intercom");
 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");
+const BROKER_PID = join(getBrokerRuntimeDir(), "broker.pid");
+const BROKER_SPAWN_LOCK = join(getBrokerRuntimeDir(), "broker.spawn.lock");
 
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => {
@@ -69,7 +73,8 @@ export async function spawnBrokerIfNeeded(
   brokerCommand: string,
   brokerArgs: readonly string[],
 ): Promise<void> {
-  await mkdir(INTERCOM_DIR, { recursive: true });
+  prepareBrokerSocketPath();
+  await warnPreviousBroker();
 
   if (await isBrokerRunning()) {
     return;
@@ -136,13 +141,20 @@ export async function isBrokerRunning(): Promise<boolean> {
   return checkSocketConnectable();
 }
 
-function readLivePid(): number | null {
-  if (!existsSync(BROKER_PID)) {
+export async function assertBrokerCanStart(): Promise<void> {
+  if (await isBrokerRunning()) {
+    throw new Error("Intercom broker is already running; refusing to replace its socket.");
+  }
+  await stopUnhealthyBrokerBeforeSpawn();
+}
+
+function readLivePid(pidPath: string): number | null {
+  if (!existsSync(pidPath)) {
     return null;
   }
   let raw: string;
   try {
-    raw = readFileSync(BROKER_PID, "utf-8");
+    raw = readFileSync(pidPath, "utf-8");
   } catch {
     return null;
   }
@@ -158,11 +170,31 @@ function readLivePid(): number | null {
   return isBrokerPidReused(pid, raw) ? null : pid;
 }
 
+async function warnPreviousBroker(): Promise<void> {
+  const previousSockets = getPreviousBrokerSocketPaths();
+  for (const socketPath of previousSockets) {
+    // Migration probes are sequential and never register or send to old peers.
+    // oxlint-disable-next-line no-await-in-loop
+    if (isOwnedBrokerSocket(socketPath) && (await checkOneSocket(socketPath))) {
+      console.warn(
+        "An older agent-directory Intercom broker is still running. Its peers are not part of shared same-user discovery until they reload with the updated extension. Existing sessions and accepted work are untouched; no legacy fallback is used.",
+      );
+      return;
+    }
+  }
+  const previousPid = readLivePid(join(getPiAgentDir(), "intercom", "broker.pid"));
+  if (previousPid !== null) {
+    console.warn(
+      `Older Intercom broker PID ${previousPid} may still own accepted work. Its peers need to reload with the updated extension to join shared same-user discovery. Nothing was stopped or replaced; no legacy fallback is used.`,
+    );
+  }
+}
+
 export async function stopUnhealthyBrokerBeforeSpawn(): Promise<void> {
   if (await checkSocketConnectable()) {
     return;
   }
-  const pid = readLivePid();
+  const pid = readLivePid(BROKER_PID);
   if (pid === null) {
     return;
   }
@@ -172,12 +204,8 @@ export async function stopUnhealthyBrokerBeforeSpawn(): Promise<void> {
 }
 
 async function checkSocketConnectable(): Promise<boolean> {
-  const preferred = getBrokerSocketPath();
-  if (isOwnedBrokerSocket(preferred) && (await checkOneSocket(preferred))) {
-    return true;
-  }
-  const legacy = getLegacyBrokerSocketPath();
-  return legacy !== preferred && isOwnedBrokerSocket(legacy) && (await checkOneSocket(legacy));
+  const socketPath = getBrokerSocketPath();
+  return isOwnedBrokerSocket(socketPath) && (await checkOneSocket(socketPath));
 }
 
 function checkOneSocket(brokerSocket: string): Promise<boolean> {

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

@@ -0,0 +1,42 @@
+import type { SessionInfo } from "../types.ts";
+import { nativePeerId } from "../session-targets.ts";
+
+export function canSeeSession(from: SessionInfo, target: SessionInfo): boolean {
+  return (
+    (from.rootSessionId ?? from.id) === (target.rootSessionId ?? target.id) ||
+    (from.parentSessionId === undefined && target.parentSessionId === undefined)
+  );
+}
+
+export function assertMainParent(
+  session: Omit<SessionInfo, "id">,
+  sessions: ReadonlyMap<string, { readonly info: SessionInfo }>,
+): void {
+  if (
+    session.parentSessionId !== undefined &&
+    sessions.get(nativePeerId(session.parentSessionId))?.info.parentSessionId !== undefined
+  ) {
+    throw new Error("Nested child sessions are not supported.");
+  }
+}
+
+/** Preserve exact-ID precedence and case-insensitive duplicate-name ambiguity. */
+export function findSessions<T extends { readonly info: SessionInfo }>(
+  sessions: ReadonlyMap<string, T>,
+  nameOrId: string,
+  fromId: string,
+): T[] {
+  const from = sessions.get(fromId);
+  if (!from) {
+    return [];
+  }
+  const byId = sessions.get(nameOrId);
+  if (byId && canSeeSession(from.info, byId.info)) {
+    return [byId];
+  }
+  const lowerName = nameOrId.toLowerCase();
+  return [...sessions.values()].filter(
+    (session) =>
+      canSeeSession(from.info, session.info) && session.info.name?.toLowerCase() === lowerName,
+  );
+}

package/src/pi-intercom/config.ts

@@ -1,12 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { Key, type KeyId } from "@earendil-works/pi-tui";
 import { getPiAgentDir } from "./agent-dir.ts";
 import { isRecord, isUnknownArray } from "./validation.ts";
 
 export interface IntercomConfig {
-  /** Toggle owned agents, or open peer messaging when the agent view is unavailable. */
-  readonly shortcut: KeyId;
   /** Broker command used to spawn the broker process (for example, Node or Bun). */
   readonly brokerCommand: string;
   /** Arguments passed to the broker command before the broker script path. */
@@ -25,7 +22,6 @@ export interface IntercomConfig {
   readonly listTimeoutMs: number;
 }
 const defaults: IntercomConfig = {
-  shortcut: Key.altShift("m"),
   brokerCommand: process.execPath,
   brokerArgs: [],
   confirmSend: false,
@@ -34,15 +30,6 @@ const defaults: IntercomConfig = {
   sendTimeoutMs: 8000,
   listTimeoutMs: 5000,
 };
-const namedKeys = new Set<string>(Object.values(Key).filter((key) => typeof key === "string"));
-function isShortcut(value: string): value is KeyId {
-  const prefix = value.match(/^(?:(?:ctrl|shift|alt|super)\+)+/)?.[0] ?? "";
-  const modifiers = prefix.split("+").filter(Boolean);
-  const key = value.slice(prefix.length);
-  return (
-    new Set(modifiers).size === modifiers.length && (namedKeys.has(key) || /^[a-z0-9]$/.test(key))
-  );
-}
 function configuredString(
   parsed: Readonly<Record<string, unknown>>,
   key: "brokerCommand" | "status",
@@ -65,19 +52,6 @@ function configuredString(
 function brokerCommand(parsed: Readonly<Record<string, unknown>>): string {
   return configuredString(parsed, "brokerCommand") ?? defaults.brokerCommand;
 }
-function configuredShortcut(parsed: Readonly<Record<string, unknown>>): KeyId {
-  if (!Object.hasOwn(parsed, "shortcut")) {
-    return defaults.shortcut;
-  }
-  if (typeof parsed.shortcut !== "string") {
-    throw new Error('"shortcut" must be a native key identifier');
-  }
-  const shortcut = parsed.shortcut.trim();
-  if (!isShortcut(shortcut)) {
-    throw new Error('"shortcut" must be a native key identifier, for example alt+shift+m');
-  }
-  return shortcut;
-}
 function configuredArgs(parsed: Readonly<Record<string, unknown>>): readonly string[] {
   if (!Object.hasOwn(parsed, "brokerArgs")) {
     return defaults.brokerArgs;
@@ -130,7 +104,6 @@ export function loadConfig(): IntercomConfig {
       throw new Error("Config must be a JSON object");
     }
     return {
-      shortcut: configuredShortcut(parsed),
       brokerCommand: brokerCommand(parsed),
       brokerArgs: configuredArgs(parsed),
       confirmSend: configuredBoolean(parsed, "confirmSend"),