@fitchmultz/pi-subagents 0.49.0 → 0.50.0

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

@@ -1,10 +1,11 @@
 import { EventEmitter } from "events";
 import type net from "net";
 import { randomUUID } from "crypto";
-import type { NativeControlEnvelope } from "../native-control-protocol.ts";
 import { writeMessage } from "./framing.ts";
 import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
+import { LastMessageRequests } from "./client-last.ts";
+import { isLastMessageQuery, isLastMessageResult } from "./last.ts";
 import {
   errorMessage,
   isRecord,
@@ -25,6 +26,8 @@ import {
   type TopicChange,
   type SessionSnapshot,
   type SendResult,
+  type LastMessageQuery,
+  type LastMessageResult,
 } from "../types.ts";
 export type { SendResult } from "../types.ts";
 
@@ -52,7 +55,6 @@ interface SendOptions {
   readonly messageId?: string;
   readonly human?: HumanMessageOrigin;
   readonly topic?: TopicUpdate;
-  readonly control?: NativeControlEnvelope;
 }
 
 function toError(error: unknown): Error {
@@ -76,6 +78,8 @@ export class IntercomClient extends EventEmitter {
   private connection: BrokerConnection | null = null;
   private _sessionId: string | null = null;
   private _topicsSupported = false;
+  private lastMessagesSupported = false;
+  private readonly lastRequests = new LastMessageRequests();
   private readonly pendingSends = new Map<
     string,
     { readonly resolve: (r: SendResult) => void; readonly reject: (e: Readonly<Error>) => void }
@@ -100,6 +104,7 @@ export class IntercomClient extends EventEmitter {
   }
 
   private failPending(error: Readonly<Error>): void {
+    this.lastRequests.fail(error);
     for (const pending of this.pendingSends.values()) {
       pending.reject(error);
     }
@@ -159,6 +164,7 @@ export class IntercomClient extends EventEmitter {
           this.connection = null;
           this._sessionId = null;
           this._topicsSupported = false;
+          this.lastMessagesSupported = false;
           this.disconnecting = false;
           this.failPending(error);
           if (established && !expected) {
@@ -174,6 +180,7 @@ export class IntercomClient extends EventEmitter {
           session: identity,
           requestedId,
           topicFrames: true,
+          lastMessages: true,
         });
       } catch (error) {
         if (this.connection === connection) {
@@ -224,6 +231,12 @@ export class IntercomClient extends EventEmitter {
       case "sessions":
         this.receiveSessions(brokerMessage);
         break;
+      case "last_request":
+        this.receiveLastRequest(brokerMessage);
+        break;
+      case "last_response":
+        this.lastRequests.receive(brokerMessage);
+        break;
       case "message":
         this.receiveMessage(brokerMessage);
         break;
@@ -252,10 +265,21 @@ export class IntercomClient extends EventEmitter {
     }
     this._sessionId = msg.sessionId;
     this._topicsSupported = msg.topicsSupported === true && msg.topicFrames === true;
+    this.lastMessagesSupported = msg.lastMessages === true;
     this.connection?.confirmRegistration();
     this.emit("_registered", { type: "registered", sessionId: msg.sessionId });
   }
 
+  private receiveLastRequest(msg: UnknownRecord): void {
+    const from = normalizeSessionInfo(msg.from);
+    if (typeof msg.requestId !== "string" || !from || !isLastMessageQuery(msg.query)) {
+      throw new Error("Invalid last-message request");
+    }
+    if (!this.emit("last_request", { requestId: msg.requestId, from, query: msg.query })) {
+      this.respondLast(msg.requestId, { error: "Recipient has no last-message reader." });
+    }
+  }
+
   private receiveMessage(msg: UnknownRecord): void {
     const message = normalizeMessage(msg.message);
     const from = normalizeSessionInfo(msg.from);
@@ -327,6 +351,25 @@ export class IntercomClient extends EventEmitter {
     return this.requestSessions().then((snapshot) => [...snapshot.sessions]);
   }
 
+  last(to: string, query: LastMessageQuery = {}): Promise<LastMessageResult> {
+    try {
+      const socket = this.requireActiveSocket();
+      if (!this.lastMessagesSupported) {
+        throw new Error("This broker does not support last-message reads; reload after it exits.");
+      }
+      return this.lastRequests.request(socket, to, query, this.listTimeoutMs);
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+  }
+
+  respondLast(requestId: string, result: unknown): void {
+    if (!isLastMessageResult(result)) {
+      throw new Error("Invalid last-message result");
+    }
+    writeMessage(this.requireActiveSocket(), { type: "last_response", requestId, result });
+  }
+
   updateTopics(
     change: TopicChange,
     onAccepted?: (snapshot: SessionSnapshot) => void,
@@ -407,7 +450,6 @@ export class IntercomClient extends EventEmitter {
       expectsReply: options.expectsReply,
       ...(options.human ? { human: options.human } : {}),
       ...(options.topic ? { topic: options.topic } : {}),
-      ...(options.control ? { control: options.control } : {}),
       delivery: messageDelivery(options),
       queueMode: options.queueMode,
       threadId: options.threadId,

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

@@ -1,6 +1,6 @@
 import net from "node:net";
 import { errorMessage } from "../../shared/unknown.ts";
-import { getBrokerSocketPath, getLegacyBrokerSocketPath, isOwnedBrokerSocket } from "./paths.ts";
+import { getBrokerSocketPath, isOwnedBrokerSocket } from "./paths.ts";
 import { createMessageReader, writeMessage } from "./framing.ts";
 
 function connectSocket(socketPath: string, timeoutMs = 500): Promise<net.Socket> {
@@ -30,23 +30,11 @@ function connectSocket(socketPath: string, timeoutMs = 500): Promise<net.Socket>
 }
 
 export 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 {
-      // Preferred and legacy sockets must be tried in order, never connected concurrently.
-      // oxlint-disable-next-line no-await-in-loop
-      return await connectSocket(candidate);
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error(errorMessage(error));
-    }
+  const socketPath = getBrokerSocketPath();
+  if (!isOwnedBrokerSocket(socketPath)) {
+    throw new Error(`Intercom broker socket is unavailable: ${socketPath}`);
   }
-  throw lastError ?? new Error(`Intercom broker socket is unavailable: ${preferred}`);
+  return await connectSocket(socketPath);
 }
 
 interface ConnectionHandlers {

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

@@ -0,0 +1,222 @@
+import type net from "node:net";
+import { randomUUID } from "node:crypto";
+import { isRecord, type UnknownRecord } from "../../shared/unknown.ts";
+import {
+  normalizeSessionInfo,
+  type LastMessageQuery,
+  type LastMessageResult,
+  type SessionInfo,
+} from "../types.ts";
+import { validateIntercomMessageSize, writeMessage } from "./framing.ts";
+import { messageSender } from "./snapshots.ts";
+import { findSessions } from "./targets.ts";
+
+export const LAST_MESSAGE_PAGE_LIMIT = 16384;
+
+function nonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function optionalEntryId(value: unknown): boolean {
+  return value === undefined || (typeof value === "string" && value.length > 0);
+}
+export function isLastMessageQuery(value: unknown): value is LastMessageQuery {
+  return (
+    isRecord(value) &&
+    optionalEntryId(value.entryId) &&
+    (value.offset === undefined || nonNegativeInteger(value.offset)) &&
+    (value.limit === undefined ||
+      (nonNegativeInteger(value.limit) &&
+        value.limit > 0 &&
+        value.limit <= LAST_MESSAGE_PAGE_LIMIT))
+  );
+}
+function pageIdentity(value: UnknownRecord): boolean {
+  return (
+    normalizeSessionInfo(value.session) !== null &&
+    (value.entryId === null || (typeof value.entryId === "string" && value.entryId.length > 0)) &&
+    typeof value.text === "string" &&
+    value.text.length <= LAST_MESSAGE_PAGE_LIMIT
+  );
+}
+function pageOffsets(value: UnknownRecord): boolean {
+  if (
+    !nonNegativeInteger(value.offset) ||
+    !nonNegativeInteger(value.totalLength) ||
+    typeof value.text !== "string"
+  ) {
+    return false;
+  }
+  const end = value.offset + value.text.length;
+  if (value.entryId === null) {
+    return end === 0 && value.totalLength === 0 && value.nextOffset === undefined;
+  }
+  if (value.nextOffset === undefined) {
+    return end === value.totalLength;
+  }
+  return value.nextOffset === end && end < value.totalLength && value.text.length > 0;
+}
+export function isLastMessageResult(value: unknown): value is LastMessageResult {
+  return (
+    isRecord(value) &&
+    (typeof value.error === "string" || (pageIdentity(value) && pageOffsets(value)))
+  );
+}
+interface LastPeer {
+  readonly socket: net.Socket;
+  readonly info: SessionInfo;
+  readonly lastMessages: boolean;
+}
+interface PendingLast {
+  readonly fromId: string;
+  readonly toId: string;
+  readonly requestId: string;
+  readonly query: LastMessageQuery;
+  readonly timer: NodeJS.Timeout;
+}
+function unavailable(
+  targets: readonly LastPeer[],
+  name: string,
+  pending: number,
+): string | undefined {
+  if (targets.length === 0) {
+    return "Session not found";
+  }
+  if (targets.length > 1) {
+    return `Multiple sessions named "${name}" are connected. Use the session ID instead.`;
+  }
+  if (!targets[0].lastMessages) {
+    return "Recipient does not support last-message reads; reload its extension.";
+  }
+  if (pending >= 128) {
+    return "Too many pending last-message reads; retry after they settle.";
+  }
+  return undefined;
+}
+function matchesPage(result: LastMessageResult, pending: PendingLast, fromId: string): boolean {
+  if ("error" in result) {
+    return true;
+  }
+  return (
+    result.session.id === fromId &&
+    result.offset === (pending.query.offset ?? 0) &&
+    (pending.query.entryId === undefined || result.entryId === pending.query.entryId) &&
+    result.text.length <= (pending.query.limit ?? LAST_MESSAGE_PAGE_LIMIT)
+  );
+}
+
+/** Correlation belongs to the broker, not the requester or the recipient's model queue. */
+export class LastMessageRelay {
+  private readonly pending = new Map<string, PendingLast>();
+  private readonly sessions: ReadonlyMap<string, LastPeer>;
+  constructor(sessions: ReadonlyMap<string, LastPeer>) {
+    this.sessions = sessions;
+  }
+
+  request(fromId: string, message: UnknownRecord): void {
+    if (
+      typeof message.requestId !== "string" ||
+      typeof message.to !== "string" ||
+      !isLastMessageQuery(message.query)
+    ) {
+      throw new Error("Invalid last message request");
+    }
+    const targets = findSessions(this.sessions, message.to, fromId);
+    const target = targets[0];
+    const from = this.sessions.get(fromId);
+    if (!from) {
+      return;
+    }
+    const error = unavailable(targets, message.to, this.pending.size);
+    if (error !== undefined) {
+      writeMessage(from.socket, {
+        type: "last_response",
+        requestId: message.requestId,
+        result: { error },
+      });
+      return;
+    }
+    const token = randomUUID();
+    const frame = {
+      type: "last_request" as const,
+      requestId: token,
+      from: messageSender(from.info),
+      query: message.query,
+    };
+    const invalid = validateIntercomMessageSize(frame);
+    if (invalid) {
+      writeMessage(from.socket, {
+        type: "last_response",
+        requestId: message.requestId,
+        result: { error: invalid.message },
+      });
+      return;
+    }
+    const timer = setTimeout(
+      () => this.finish(token, { error: "Last-message read timed out" }),
+      5000,
+    );
+    timer.unref();
+    this.pending.set(token, {
+      fromId,
+      toId: target.info.id,
+      requestId: message.requestId,
+      query: message.query,
+      timer,
+    });
+    try {
+      writeMessage(target.socket, frame);
+    } catch {
+      this.finish(token, { error: "Recipient disconnected before last-message read" });
+    }
+  }
+
+  respond(fromId: string, message: UnknownRecord): void {
+    if (typeof message.requestId !== "string") {
+      throw new Error("Invalid last message response");
+    }
+    const pending = this.pending.get(message.requestId);
+    if (!pending || pending.toId !== fromId) {
+      return;
+    }
+    const result = message.result;
+    this.finish(
+      message.requestId,
+      isLastMessageResult(result) && matchesPage(result, pending, fromId)
+        ? result
+        : { error: "Recipient returned an invalid last-message page" },
+    );
+  }
+
+  disconnected(sessionId: string): void {
+    for (const [token, pending] of this.pending) {
+      if (pending.fromId === sessionId || pending.toId === sessionId) {
+        this.finish(token, { error: "Peer disconnected during last-message read" });
+      }
+    }
+  }
+
+  private finish(token: string, result: LastMessageResult): void {
+    const pending = this.pending.get(token);
+    if (!pending) {
+      return;
+    }
+    clearTimeout(pending.timer);
+    this.pending.delete(token);
+    const from = this.sessions.get(pending.fromId);
+    if (!from) {
+      return;
+    }
+    const frame = { type: "last_response" as const, requestId: pending.requestId, result };
+    const invalid = validateIntercomMessageSize(frame);
+    writeMessage(
+      from.socket,
+      invalid
+        ? {
+            type: "last_response",
+            requestId: pending.requestId,
+            result: { error: invalid.message },
+          }
+        : frame,
+    );
+  }
+}

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 } 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,13 +36,26 @@ export function isOwnedBrokerSocket(socketPath: string): boolean {
   }
 }
 
-export function getBrokerSocketPath(agentDir: string = getPiAgentDir()): string {
+/** A deployment can explicitly opt out of same-user discovery with a private runtime directory. */
+export function getBrokerRuntimeDir(): 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 directory = configured ?? join("/tmp", `pi-intercom-${uid}`);
+  if (
+    !isAbsolute(directory) ||
+    directory.includes("\0") ||
+    Buffer.byteLength(join(directory, "broker.sock")) > MAX_UNIX_SOCKET_PATH_BYTES
+  ) {
+    throw new Error("PI_INTERCOM_RUNTIME_DIR must be an absolute short Unix socket directory.");
+  }
+  return directory;
+}
+
+export function getBrokerSocketPath(): string {
+  return join(getBrokerRuntimeDir(), "broker.sock");
 }
 
 export function prepareBrokerSocketPath(): string {

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

@@ -0,0 +1,38 @@
+import type net from "node:net";
+import { createMessageReader } from "./framing.ts";
+
+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,
+  );
+}