@fitchmultz/pi-subagents 0.52.19 → 0.52.21

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

@@ -4,20 +4,41 @@ import { writeMessage } from "./framing.ts";
 /** Parking negotiation and its single outstanding broker acknowledgement. */
 export class ParkRequests {
   supported = false;
-  private acknowledged?: ((parked: boolean) => void) | undefined;
+  private state:
+    | { readonly kind: "idle" }
+    | {
+        readonly kind: "pending";
+        readonly promise: Promise<boolean>;
+        readonly resolve: (parked: boolean) => void;
+      } = { kind: "idle" };
   settle(parked: boolean): void {
-    this.acknowledged?.(parked);
+    const state = this.state;
+    this.state = { kind: "idle" };
+    if (state.kind === "pending") {
+      state.resolve(parked);
+    }
   }
   /** True once the broker retains later input; false when it cannot or the socket closed. */
   request(socket: () => net.Socket, on: boolean): Promise<boolean> {
-    return new Promise((resolve) => {
-      this.acknowledged = on && this.supported ? resolve : undefined;
+    if (on && this.state.kind === "pending") {
+      return this.state.promise;
+    }
+    const { promise, resolve, reject } = Promise.withResolvers<boolean>();
+    this.settle(false);
+    if (on && this.supported) {
+      this.state = { kind: "pending", promise, resolve };
+    }
+    try {
       if (this.supported) {
         writeMessage(socket(), { type: on ? "park" : "unpark" });
       }
-      if (this.acknowledged === undefined) {
+      if (this.state.kind === "idle") {
         resolve(false);
       }
-    });
+    } catch (error) {
+      this.state = { kind: "idle" };
+      reject(error);
+    }
+    return promise;
   }
 }

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

@@ -4,6 +4,7 @@ import { randomUUID } from "crypto";
 import { writeMessage } from "./framing.ts";
 import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
+import { PendingRequests } from "./pending-requests.ts";
 import { LastMessageRequests, lastRequest } from "./client-last.ts";
 import { ParkRequests } from "./client-park.ts";
 import { WakeMessages } from "./client-wake.ts";
@@ -62,6 +63,10 @@ function messageDelivery(options: SendOptions): MessageDelivery | undefined {
   return "steer";
 }
 
+type ClientPhase =
+  | { readonly kind: "idle" | "connected" }
+  | { readonly kind: "connecting" | "closing"; readonly task: Promise<void> };
+
 export class IntercomClient extends EventEmitter {
   private connection: BrokerConnection | null = null;
   private _sessionId: string | null = null;
@@ -70,20 +75,16 @@ export class IntercomClient extends EventEmitter {
   readonly wakes = new WakeMessages(this, () => this.requireActiveSocket());
   private guardedDeliverySupported = false;
   private readonly lastRequests: LastMessageRequests;
-  private readonly pendingSends = new Map<
-    string,
-    { readonly resolve: (r: SendResult) => void; readonly reject: (e: Readonly<Error>) => void }
-  >();
-  private readonly pendingLists = new Map<
-    string,
-    {
-      readonly resolve: (snapshot: SessionSnapshot) => void;
-      readonly reject: (e: Readonly<Error>) => void;
-      readonly reader: SnapshotReader;
-    }
-  >();
-  private connecting = false;
-  private disconnecting = false;
+  private readonly pendingSends = new PendingRequests<{
+    readonly resolve: (r: SendResult) => void;
+    readonly reject: (e: Readonly<Error>) => void;
+  }>();
+  private readonly pendingLists = new PendingRequests<{
+    readonly resolve: (snapshot: SessionSnapshot) => void;
+    readonly reject: (e: Readonly<Error>) => void;
+    readonly reader: SnapshotReader;
+  }>();
+  private phase: ClientPhase = { kind: "idle" };
   private readonly sendTimeoutMs: number;
   private readonly listTimeoutMs: number;
 
@@ -96,14 +97,8 @@ 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);
-    }
-    this.pendingSends.clear();
-    for (const pending of this.pendingLists.values()) {
-      pending.reject(error);
-    }
-    this.pendingLists.clear();
+    this.pendingSends.fail(error);
+    this.pendingLists.fail(error);
   }
 
   get sessionId(): string | null {
@@ -119,13 +114,13 @@ export class IntercomClient extends EventEmitter {
   isConnected(): boolean {
     return (
       (this._sessionId ?? "").length > 0 &&
-      !this.disconnecting &&
+      this.phase.kind !== "closing" &&
       this.connection?.isActive() === true
     );
   }
 
   private requireActiveSocket(): net.Socket {
-    if (this.disconnecting) {
+    if (this.phase.kind === "closing") {
       throw new Error("Client disconnecting");
     }
     const connection = this.connection;
@@ -139,60 +134,71 @@ export class IntercomClient extends EventEmitter {
   }
 
   async connect(session: Omit<SessionInfo, "id">, requestedId?: string): Promise<void> {
-    if (this.connection || this.connecting) {
+    if (this.connection || this.phase.kind !== "idle") {
       throw new Error("Already connected");
     }
-    this.connecting = true;
+    const task = this.establish(session, requestedId);
+    this.phase = { kind: "connecting", task };
     try {
-      const socket = await connectBrokerSocket();
-      const connection = new BrokerConnection(socket, {
-        message: (message) => this.handleBrokerMessage(message),
-        error: (error) => {
-          this.emit("error", error);
-        },
-        closed: (error, expected) => {
-          if (this.connection !== connection) {
-            return;
-          }
-          const established = this._sessionId !== null;
-          this.connection = null;
-          this._sessionId = null;
-          this._topicsSupported = false;
-          this.parking.settle(false);
-          this.guardedDeliverySupported = false;
-          this.wakes.supported = false;
-          this.disconnecting = false;
-          this.failPending(error);
-          if (established && !expected) {
-            this.emit("disconnected", error);
-          }
-        },
-      });
-      this.connection = connection;
-      const { topics, subscriptions, ...identity } = session;
-      try {
-        await connection.start({
-          type: "register",
-          session: identity,
-          requestedId,
-          topicFrames: true,
-          lastMessages: true,
-          parking: true,
-          receiptReads: 1,
-          guardedDelivery: 1,
-          ...this.wakes.registration(),
-        });
-      } catch (error) {
-        if (this.connection === connection) {
-          this.connection = null;
-        }
-        throw error;
-      }
-      if (this.supportsTopics) {
-        await this.restoreTopics(topics, subscriptions);
-      }
+      await task;
     } finally {
-      this.connecting = false;
+      if (this.phase.kind === "connecting" && this.phase.task === task) {
+        this.phase = { kind: this.isConnected() ? "connected" : "idle" };
+      }
+    }
+  }
+
+  private async establish(session: Omit<SessionInfo, "id">, requestedId?: string): Promise<void> {
+    const socket = await connectBrokerSocket();
+    const connection = new BrokerConnection(socket, {
+      message: (message) => this.handleBrokerMessage(message),
+      error: (error) => {
+        this.emit("error", error);
+      },
+      closed: (error, expected) => {
+        if (this.connection !== connection) {
+          return;
+        }
+        const established = this._sessionId !== null;
+        this.connection = null;
+        this._sessionId = null;
+        this._topicsSupported = false;
+        this.parking.settle(false);
+        this.guardedDeliverySupported = false;
+        this.wakes.supported = false;
+        if (this.phase.kind === "connected") {
+          this.phase = { kind: "idle" };
+        }
+        this.failPending(error);
+        if (established && !expected) {
+          this.emit("disconnected", error);
+        }
+      },
+    });
+    this.connection = connection;
+    if (this.phase.kind === "closing") {
+      await connection.disconnect();
+      throw new Error("Client disconnecting");
+    }
+    const { topics, subscriptions, ...identity } = session;
+    try {
+      await connection.start({
+        type: "register",
+        session: identity,
+        requestedId,
+        topicFrames: true,
+        lastMessages: true,
+        parking: true,
+        receiptReads: 1,
+        guardedDelivery: 1,
+        ...this.wakes.registration(),
+      });
+    } catch (error) {
+      await connection.disconnect();
+      throw error;
+    }
+    if (this.supportsTopics) {
+      await this.restoreTopics(topics, subscriptions);
     }
   }
 
@@ -301,12 +307,11 @@ export class IntercomClient extends EventEmitter {
     if (type !== "delivered" && typeof reason !== "string") {
       throw new Error(`Invalid ${errorMessage(type)} message`);
     }
-    const pending = this.pendingSends.get(messageId);
+    const pending = this.pendingSends.take(messageId);
     // Late responses are harmless after the caller has timed out.
     if (!pending) {
       return;
     }
-    this.pendingSends.delete(messageId);
     pending.resolve({
       id: messageId,
       accepted: type !== "delivery_failed",
@@ -330,14 +335,12 @@ export class IntercomClient extends EventEmitter {
       return;
     }
     if (typeof error === "string") {
-      this.pendingLists.delete(requestId);
-      pending.reject(new Error(error));
+      this.pendingLists.take(requestId)?.reject(new Error(error));
       return;
     }
     pending.reader.append(sessions, receipts);
     if (more !== true) {
-      this.pendingLists.delete(requestId);
-      pending.resolve(pending.reader.finish());
+      this.pendingLists.take(requestId)?.resolve(pending.reader.finish());
     }
   }
 
@@ -345,14 +348,30 @@ export class IntercomClient extends EventEmitter {
     return this.parking.request(() => this.requireActiveSocket(), on);
   }
 
-  async disconnect(): Promise<void> {
-    const connection = this.connection;
-    if (!connection) {
-      return;
+  disconnect(): Promise<void> {
+    const phase = this.phase;
+    if (phase.kind === "closing") {
+      return phase.task;
     }
-    this.disconnecting = true;
+    const connecting = phase.kind === "connecting" ? phase.task : undefined;
+    const task = Promise.resolve().then(() => this.close(connecting));
+    this.phase = { kind: "closing", task };
+    return task;
+  }
+
+  private async close(connecting: Promise<void> | undefined): Promise<void> {
     this.failPending(new Error("Client disconnected"));
-    await connection.disconnect();
+    try {
+      await this.connection?.disconnect();
+      try {
+        await connecting;
+      } catch {
+        // The connect caller owns acquisition failure; close still joins any acquired socket.
+      }
+      await this.connection?.disconnect();
+    } finally {
+      this.phase = { kind: "idle" };
+    }
   }
 
   listSessions(): Promise<SessionInfo[]> {
@@ -396,8 +415,8 @@ export class IntercomClient extends EventEmitter {
 
     return new Promise((resolve, reject) => {
       const requestId = randomUUID();
+      const reader = new SnapshotReader();
       const wrappedResolve = (snapshot: SessionSnapshot) => {
-        clearTimeout(timeout);
         try {
           // Commit confirmed subscriptions before handling a following message in the same read.
           onAccepted?.(snapshot);
@@ -407,23 +426,19 @@ export class IntercomClient extends EventEmitter {
         }
       };
       const wrappedReject = (error: Readonly<Error>) => {
-        clearTimeout(timeout);
+        reader.fail();
         reject(error);
       };
-      const timeout = setTimeout(() => {
-        if (this.pendingLists.has(requestId)) {
-          this.pendingLists.delete(requestId);
-          wrappedReject(
-            Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }),
-          );
-        }
-      }, this.listTimeoutMs);
-      timeout.unref();
-      this.pendingLists.set(requestId, {
-        resolve: wrappedResolve,
-        reject: wrappedReject,
-        reader: new SnapshotReader(),
-      });
+      this.pendingLists.set(
+        requestId,
+        {
+          resolve: wrappedResolve,
+          reject: wrappedReject,
+          reader,
+        },
+        this.listTimeoutMs,
+        () => Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }),
+      );
       try {
         writeMessage(socket, {
           type: "list",
@@ -432,9 +447,7 @@ export class IntercomClient extends EventEmitter {
           ...(change ? { change } : {}),
         });
       } catch (error) {
-        clearTimeout(timeout);
-        this.pendingLists.delete(requestId);
-        reject(toError(error));
+        this.pendingLists.take(requestId)?.reject(toError(error));
       }
     });
   }
@@ -456,7 +469,7 @@ export class IntercomClient extends EventEmitter {
     }
 
     const messageId = options.messageId ?? (options.guard ? "" : randomUUID());
-    if (this.pendingSends.has(messageId)) {
+    if (this.pendingSends.get(messageId)) {
       return Promise.reject(new Error("Message ID already has a pending send"));
     }
     const message: Message = {
@@ -482,22 +495,12 @@ export class IntercomClient extends EventEmitter {
       return Promise.reject(new Error("Invalid message format"));
     }
     return new Promise((resolve, reject) => {
-      const wrappedResolve = (result: SendResult) => {
-        clearTimeout(timeout);
-        resolve(result);
-      };
-      const wrappedReject = (error: Readonly<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 });
+      this.pendingSends.set(
+        messageId,
+        { resolve, reject },
+        this.sendTimeoutMs,
+        () => new Error("Send timeout"),
+      );
 
       try {
         writeMessage(socket, {
@@ -506,9 +509,7 @@ export class IntercomClient extends EventEmitter {
           message: this._topicsSupported ? compactTopicMessage(message) : message,
         });
       } catch (error) {
-        clearTimeout(timeout);
-        this.pendingSends.delete(messageId);
-        reject(toError(error));
+        this.pendingSends.take(messageId)?.reject(toError(error));
       }
     });
   }
@@ -524,7 +525,7 @@ export class IntercomClient extends EventEmitter {
     readonly subscriptions?: SessionInfo["subscriptions"] | undefined;
     readonly topics?: readonly TopicUpdate[] | undefined;
   }): void {
-    if (this.disconnecting) {
+    if (this.phase.kind === "closing") {
       return;
     }
 

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

@@ -43,16 +43,20 @@ interface ConnectionHandlers {
   readonly closed: (error: Readonly<Error>, expected: boolean) => void;
 }
 
+type ConnectionPhase =
+  | { readonly kind: "acquired" | "active" | "failed" | "closed" }
+  | {
+      readonly kind: "registering";
+      readonly resolve: () => void;
+      readonly reject: (error: Readonly<Error>) => void;
+      readonly timer: NodeJS.Timeout;
+    }
+  | { readonly kind: "closing"; readonly task: Promise<void>; readonly registered: boolean };
+
 /** One socket owns registration, read/error listeners, and graceful shutdown. */
 export class BrokerConnection {
-  private registered = false;
-  private closing = false;
+  private phase: ConnectionPhase = { kind: "acquired" };
   private failure: Readonly<Error> | null = null;
-  private registration: {
-    readonly resolve: () => void;
-    readonly reject: (error: Readonly<Error>) => void;
-  } | null = null;
-  private registrationTimer: NodeJS.Timeout | null = null;
   private readonly reader: (data: Buffer) => void;
 
   readonly socket: net.Socket;
@@ -69,12 +73,9 @@ export class BrokerConnection {
 
   start(registration: unknown): Promise<void> {
     return new Promise((resolve, reject) => {
-      this.registration = { resolve, reject };
-      this.registrationTimer = setTimeout(
-        () => this.failRegistration(new Error("Connection timeout")),
-        10000,
-      );
-      this.registrationTimer.unref();
+      const timer = setTimeout(() => this.failRegistration(new Error("Connection timeout")), 10000);
+      timer.unref();
+      this.phase = { kind: "registering", resolve, reject, timer };
       try {
         writeMessage(this.socket, registration);
       } catch (error) {
@@ -84,23 +85,28 @@ export class BrokerConnection {
   }
 
   confirmRegistration(): void {
-    this.registered = true;
-    const pending = this.registration;
-    this.clearRegistration();
-    pending?.resolve();
+    const pending = this.takeRegistration();
+    if (pending !== undefined) {
+      this.phase = { kind: "active" };
+      pending.resolve();
+    }
   }
 
-  private clearRegistration(): void {
-    if (this.registrationTimer) {
-      clearTimeout(this.registrationTimer);
+  private takeRegistration() {
+    const pending = this.phase;
+    if (pending.kind !== "registering") {
+      return;
     }
-    this.registrationTimer = null;
-    this.registration = null;
+    clearTimeout(pending.timer);
+    this.phase = { kind: "acquired" };
+    return pending;
   }
 
   private failRegistration(error: Readonly<Error>): void {
-    const pending = this.registration;
-    this.clearRegistration();
+    const pending = this.takeRegistration();
+    if (this.phase.kind !== "closing") {
+      this.phase = { kind: "failed" };
+    }
     this.failure = error;
     this.socket.destroy();
     pending?.reject(error);
@@ -127,19 +133,23 @@ export class BrokerConnection {
   };
 
   private readonly onClose = (): void => {
-    const pending = this.registration;
-    this.clearRegistration();
+    const closing = this.phase.kind === "closing";
+    const pending = this.takeRegistration();
+    this.phase = { kind: "closed" };
     this.socket.off("data", this.reader);
     this.socket.off("error", this.onError);
     this.socket.off("close", this.onClose);
     pending?.reject(new Error("Connection closed before registration"));
-    this.handlers.closed(this.failure ?? new Error("Client disconnected"), this.closing);
+    this.handlers.closed(this.failure ?? new Error("Client disconnected"), closing);
   };
 
+  private get registered(): boolean {
+    return this.phase.kind === "active" || (this.phase.kind === "closing" && this.phase.registered);
+  }
+
   isActive(): boolean {
     return (
-      this.registered &&
-      !this.closing &&
+      this.phase.kind === "active" &&
       !this.socket.destroyed &&
       !this.socket.writableEnded &&
       this.socket.writable
@@ -147,15 +157,18 @@ export class BrokerConnection {
   }
 
   disconnect(): Promise<void> {
-    this.closing = true;
+    const phase = this.phase;
+    if (phase.kind === "closing") {
+      return phase.task;
+    }
+    if (phase.kind === "closed") {
+      return Promise.resolve();
+    }
+    const pending = this.takeRegistration();
+    pending?.reject(new Error("Client disconnected before registration"));
     this.failure = null;
-    return new Promise((resolve) => {
-      let settled = false;
+    const task = new Promise<void>((resolve) => {
       const finish = () => {
-        if (settled) {
-          return;
-        }
-        settled = true;
         clearTimeout(timeout);
         this.socket.off("close", finish);
         this.socket.off("error", onError);
@@ -169,12 +182,18 @@ export class BrokerConnection {
       }, 2000);
       this.socket.once("close", finish);
       this.socket.once("error", onError);
-      try {
+    });
+    this.phase = { kind: "closing", task, registered: phase.kind === "active" };
+    try {
+      if (phase.kind === "active" || phase.kind === "registering") {
         writeMessage(this.socket, { type: "unregister" });
         this.socket.end();
-      } catch {
+      } else {
         this.socket.destroy();
       }
-    });
+    } catch {
+      this.socket.destroy();
+    }
+    return task;
   }
 }

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

@@ -90,10 +90,15 @@ class MessageBuffer {
   }
 }
 
+type FrameState =
+  | { readonly kind: "header" }
+  | { readonly kind: "payload"; readonly length: number }
+  | { readonly kind: "failed" };
+
 /**
  * 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.
+ * Protocol or handler errors end reading and are reported so the caller can close the socket.
  */
 export function createMessageReader(
   onMessage: (msg: unknown) => void,
@@ -101,32 +106,39 @@ export function createMessageReader(
   limit = MAX_FRAME_SIZE_BYTES,
 ): (data: Buffer) => void {
   const buffer = new MessageBuffer();
-  let length: number | undefined;
+  let state: FrameState = { kind: "header" };
+  const fail = (error: Readonly<Error>) => {
+    state = { kind: "failed" };
+    buffer.clear();
+    onError(error);
+  };
 
   return (data: Buffer) => {
+    if (state.kind === "failed") {
+      return;
+    }
     buffer.append(data);
 
-    while (buffer.length >= (length ?? 4)) {
-      if (length === undefined) {
-        length = buffer.read(4).readUInt32BE(0);
+    while (buffer.length >= (state.kind === "payload" ? state.length : 4)) {
+      if (state.kind === "header") {
+        const length = buffer.read(4).readUInt32BE(0);
         if (length > limit) {
-          onError(new Error(`Intercom frame too large (${length} bytes; max ${limit})`));
-          buffer.clear();
-          length = undefined;
+          fail(new Error(`Intercom frame too large (${length} bytes; max ${limit})`));
           return;
         }
+        state = { kind: "payload", length };
         continue;
       }
 
-      const payload = buffer.read(length);
-      length = undefined;
+      const payload = buffer.read(state.length);
+      state = { kind: "header" };
 
       let msg: unknown;
       try {
         msg = JSON.parse(payload.toString("utf-8"));
       } catch (error) {
         const message = errorMessage(error);
-        onError(new Error(`Failed to parse intercom message: ${message}`, { cause: error }));
+        fail(new Error(`Failed to parse intercom message: ${message}`, { cause: error }));
         return;
       }
 
@@ -134,7 +146,7 @@ export function createMessageReader(
         onMessage(msg);
       } catch (error) {
         const message = errorMessage(error);
-        onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
+        fail(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
         return;
       }
     }