@fitchmultz/pi-subagents 0.52.20 → 0.52.22

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

@@ -63,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;
@@ -80,8 +84,7 @@ export class IntercomClient extends EventEmitter {
     readonly reject: (e: Readonly<Error>) => void;
     readonly reader: SnapshotReader;
   }>();
-  private connecting = false;
-  private disconnecting = false;
+  private phase: ClientPhase = { kind: "idle" };
   private readonly sendTimeoutMs: number;
   private readonly listTimeoutMs: number;
 
@@ -111,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;
@@ -131,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);
     }
   }
 
@@ -334,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[]> {
@@ -495,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;
       }
     }

package/src/pi-intercom/broker/replace-deliveries.ts

@@ -0,0 +1,56 @@
+import type { Message, SessionInfo } from "../types.ts";
+
+const REPLACE_DELIVERY_DELAY_MS = 1500;
+
+interface StagedDelivery {
+  readonly fromId: string;
+  readonly toId: string;
+  readonly from: SessionInfo;
+  readonly message: Message;
+  readonly timer: NodeJS.Timeout;
+}
+
+/** Only broker-staged messages remain replaceable; forwarding ends this owner's authority. */
+export class ReplaceDeliveries {
+  private readonly pending = new Map<string, StagedDelivery>();
+  private readonly deliver: (toId: string, from: SessionInfo, message: Message) => string | null;
+
+  constructor(deliver: (toId: string, from: SessionInfo, message: Message) => string | null) {
+    this.deliver = deliver;
+  }
+
+  stage(fromId: string, toId: string, from: SessionInfo, message: Message): void {
+    const key = `${fromId}\0${toId}\0${message.threadId ?? ""}`;
+    this.take(key);
+    const timer = setTimeout(() => this.flush(key), REPLACE_DELIVERY_DELAY_MS);
+    timer.unref();
+    this.pending.set(key, { fromId, toId, from, message, timer });
+  }
+
+  private take(key: string): StagedDelivery | undefined {
+    const pending = this.pending.get(key);
+    if (pending !== undefined) {
+      this.pending.delete(key);
+      clearTimeout(pending.timer);
+    }
+    return pending;
+  }
+
+  private flush(key: string): void {
+    const pending = this.take(key);
+    if (pending !== undefined) {
+      this.deliver(pending.toId, pending.from, pending.message);
+    }
+  }
+
+  disconnected(sessionId: string): void {
+    for (const [key, pending] of this.pending) {
+      if (
+        pending.toId === sessionId ||
+        (pending.fromId === sessionId && pending.message.expectsReply === true)
+      ) {
+        this.take(key);
+      }
+    }
+  }
+}

package/src/pi-intercom/connection.ts

@@ -43,8 +43,10 @@ export class IntercomConnection {
   private parked: IntercomClient | null = null;
   private reconnectTimer: NodeJS.Timeout | null = null;
   private startupTimer: NodeJS.Timeout | null = null;
-  private connecting: Promise<IntercomTransport> | null = null;
-  private connectingGeneration: number | null = null;
+  private connecting: {
+    readonly task: Promise<IntercomTransport>;
+    readonly generation: number;
+  } | null = null;
   private attempt = 0;
   private readonly lifecycle: Lifecycle;
   private readonly config: IntercomConfig;
@@ -352,8 +354,8 @@ export class IntercomConnection {
     if (!ctx || generation !== this.lifecycle.generation) {
       throw new Error("Intercom shutting down");
     }
-    if (this.connecting && this.connectingGeneration === generation) {
-      return this.connecting;
+    if (this.connecting?.generation === generation) {
+      return this.connecting.task;
     }
     if (this.client?.isConnected() === true) {
       return this.client;
@@ -365,8 +367,7 @@ export class IntercomConnection {
     this.clearReconnect();
     // Publish ownership before registration, which can synchronously invoke subscribers.
     const attempt = Promise.resolve().then(() => this.connect(ctx, generation, sessionId));
-    this.connecting = attempt;
-    this.connectingGeneration = generation;
+    this.connecting = { task: attempt, generation };
     return await this.finishAttempt(attempt, ctx, generation);
   }
   private async finishAttempt(
@@ -381,9 +382,8 @@ export class IntercomConnection {
       retry = this.lifecycle.live(ctx, generation) !== null;
       throw error;
     } finally {
-      if (this.connecting === attempt) {
+      if (this.connecting?.task === attempt) {
         this.connecting = null;
-        this.connectingGeneration = null;
       }
       if (retry) {
         this.scheduleReconnect();
@@ -394,7 +394,7 @@ export class IntercomConnection {
     this.clearTimers();
     this.cancelWakes();
     // The bounded launcher attempt is joined before socket shutdown.
-    await Promise.allSettled([this.connecting]);
+    await Promise.allSettled([this.connecting?.task]);
     if (this.client) {
       await this.client.disconnect();
       this.client = null;

package/src/pi-intercom/inbound-journal.ts

@@ -191,13 +191,16 @@ export class InboundJournal {
           pending.from.id === entry.from.id &&
           pending.message.threadId === entry.message.threadId
         ) {
-          this.consume(pending.message.id);
-          this.replies.markReplied(pending.message.id);
+          this.supersede(pending.message.id);
         }
       }
     }
     this.pending.set(entry.message.id, entry);
   }
+  private supersede(id: string): void {
+    this.consume(id);
+    this.replies.markReplied(id);
+  }
   setStage(entry: PendingInboundMessage, stage: PendingInboundMessage["stage"]): void {
     if (entry.stage === stage) {
       return;

package/src/shared/journal-frames.ts

@@ -16,13 +16,15 @@ export interface JournalOptions {
   readonly stringChunk?: StringChunk | undefined;
 }
 
+type RecordState =
+  | { readonly kind: "blank" | "reading" }
+  | { readonly kind: "invalid"; readonly error: unknown };
+
 /** Byte-framed JSONL. Publication framing is independent of malformed-record tolerance. */
 export class JournalFrames {
   private projection: JsonProjection;
   private decoder = new TextDecoder("utf8", { fatal: true });
-  private error: unknown;
-  private failed = false;
-  private nonblank = false;
+  private state: RecordState = { kind: "blank" };
   private start: number;
   offset: number;
   private readonly policy: JournalPolicy;
@@ -48,20 +50,20 @@ export class JournalFrames {
     return new JsonProjection(this.select, this.options.stringChunk);
   }
   private part(bytes: Buffer): void {
-    if (!this.nonblank && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
-      this.nonblank = true;
+    if (this.state.kind === "invalid") {
+      return;
     }
-    if (!this.failed) {
-      try {
-        this.projection.write(this.decoder.decode(bytes, { stream: true }));
-      } catch (error) {
-        this.failed = true;
-        this.error = error;
-      }
+    if (this.state.kind === "blank" && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
+      this.state = { kind: "reading" };
+    }
+    try {
+      this.projection.write(this.decoder.decode(bytes, { stream: true }));
+    } catch (error) {
+      this.state = { kind: "invalid", error };
     }
   }
   private finishRecord(end: number): JournalRecord | undefined {
-    if (!this.nonblank || this.failed) {
+    if (this.state.kind !== "reading") {
       return undefined;
     }
     try {
@@ -72,17 +74,16 @@ export class JournalFrames {
       }
       return { value, start: this.start, end };
     } catch (error) {
-      this.failed = true;
-      this.error = error;
+      this.state = { kind: "invalid", error };
       return undefined;
     }
   }
   private commit(end: number): void {
     const start = this.start;
     const record = this.finishRecord(end);
-    const failed = this.failed;
-    const error = this.error;
-    if (failed && this.policy !== "inspect") {
+    const state = this.state;
+    if (state.kind === "invalid" && this.policy !== "inspect") {
+      const { error } = state;
       throw new SyntaxError(`Invalid JSONL record at byte ${start}: ${errorDescription(error)}`, {
         cause: error,
       });
@@ -90,10 +91,8 @@ export class JournalFrames {
     this.start = end;
     this.projection = this.newProjection();
     this.decoder = new TextDecoder("utf8", { fatal: true });
-    this.error = undefined;
-    this.failed = false;
-    this.nonblank = false;
-    if (!failed && record) {
+    this.state = { kind: "blank" };
+    if (record) {
       this.record(record);
     }
   }
@@ -110,7 +109,7 @@ export class JournalFrames {
   }
   finish(): number {
     if (this.requireNewline) {
-      if (this.policy === "strict" && this.nonblank) {
+      if (this.policy === "strict" && this.state.kind !== "blank") {
         throw new SyntaxError(`Unpublished JSONL record at byte ${this.start}: newline required`);
       }
     } else if (this.offset > this.start) {