@fitchmultz/pi-subagents 0.52.19 → 0.52.21

package/dist/pi-intercom/broker/client.js

@@ -3,6 +3,7 @@ import { randomUUID } from "crypto";
 import { writeMessage } from "./framing.js";
 import { BrokerConnection, connectBrokerSocket } from "./connection.js";
 import { SnapshotReader } from "./snapshot-reader.js";
+import { PendingRequests } from "./pending-requests.js";
 import { LastMessageRequests, lastRequest } from "./client-last.js";
 import { ParkRequests } from "./client-park.js";
 import { WakeMessages } from "./client-wake.js";
@@ -36,10 +37,9 @@ export class IntercomClient extends EventEmitter {
     wakes = new WakeMessages(this, () => this.requireActiveSocket());
     guardedDeliverySupported = false;
     lastRequests;
-    pendingSends = new Map();
-    pendingLists = new Map();
-    connecting = false;
-    disconnecting = false;
+    pendingSends = new PendingRequests();
+    pendingLists = new PendingRequests();
+    phase = { kind: "idle" };
     sendTimeoutMs;
     listTimeoutMs;
     constructor(options = {}) {
@@ -50,14 +50,8 @@ export class IntercomClient extends EventEmitter {
     }
     failPending(error) {
         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() {
         return this._sessionId;
@@ -70,11 +64,11 @@ export class IntercomClient extends EventEmitter {
     }
     isConnected() {
         return ((this._sessionId ?? "").length > 0 &&
-            !this.disconnecting &&
+            this.phase.kind !== "closing" &&
             this.connection?.isActive() === true);
     }
     requireActiveSocket() {
-        if (this.disconnecting) {
+        if (this.phase.kind === "closing") {
             throw new Error("Client disconnecting");
         }
         const connection = this.connection;
@@ -87,62 +81,72 @@ export class IntercomClient extends EventEmitter {
         return connection.socket;
     }
     async connect(session, requestedId) {
-        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(),
-                });
+            await task;
+        }
+        finally {
+            if (this.phase.kind === "connecting" && this.phase.task === task) {
+                this.phase = { kind: this.isConnected() ? "connected" : "idle" };
             }
-            catch (error) {
-                if (this.connection === connection) {
-                    this.connection = null;
+        }
+    }
+    async establish(session, requestedId) {
+        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;
                 }
-                throw error;
-            }
-            if (this.supportsTopics) {
-                await this.restoreTopics(topics, subscriptions);
-            }
+                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");
         }
-        finally {
-            this.connecting = false;
+        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);
         }
     }
     async restoreTopics(topics, subscriptions) {
@@ -240,12 +244,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",
@@ -266,27 +269,42 @@ 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());
         }
     }
     park(on = true) {
         return this.parking.request(() => this.requireActiveSocket(), on);
     }
-    async disconnect() {
-        const connection = this.connection;
-        if (!connection) {
-            return;
-        }
-        this.disconnecting = true;
+    disconnect() {
+        const phase = this.phase;
+        if (phase.kind === "closing") {
+            return phase.task;
+        }
+        const connecting = phase.kind === "connecting" ? phase.task : undefined;
+        const task = Promise.resolve().then(() => this.close(connecting));
+        this.phase = { kind: "closing", task };
+        return task;
+    }
+    async close(connecting) {
         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() {
         return this.requestSessions().then((snapshot) => [...snapshot.sessions]);
@@ -319,8 +337,8 @@ export class IntercomClient extends EventEmitter {
         }
         return new Promise((resolve, reject) => {
             const requestId = randomUUID();
+            const reader = new SnapshotReader();
             const wrappedResolve = (snapshot) => {
-                clearTimeout(timeout);
                 try {
                     // Commit confirmed subscriptions before handling a following message in the same read.
                     onAccepted?.(snapshot);
@@ -331,21 +349,14 @@ export class IntercomClient extends EventEmitter {
                 }
             };
             const wrappedReject = (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(),
-            });
+                reader,
+            }, this.listTimeoutMs, () => Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }));
             try {
                 writeMessage(socket, {
                     type: "list",
@@ -355,9 +366,7 @@ export class IntercomClient extends EventEmitter {
                 });
             }
             catch (error) {
-                clearTimeout(timeout);
-                this.pendingLists.delete(requestId);
-                reject(toError(error));
+                this.pendingLists.take(requestId)?.reject(toError(error));
             }
         });
     }
@@ -377,7 +386,7 @@ export class IntercomClient extends EventEmitter {
             return Promise.reject(toError(error));
         }
         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 = {
@@ -402,22 +411,7 @@ export class IntercomClient extends EventEmitter {
             return Promise.reject(new Error("Invalid message format"));
         }
         return new Promise((resolve, reject) => {
-            const wrappedResolve = (result) => {
-                clearTimeout(timeout);
-                resolve(result);
-            };
-            const wrappedReject = (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, {
                     type: "send",
@@ -426,14 +420,12 @@ export class IntercomClient extends EventEmitter {
                 });
             }
             catch (error) {
-                clearTimeout(timeout);
-                this.pendingSends.delete(messageId);
-                reject(toError(error));
+                this.pendingSends.take(messageId)?.reject(toError(error));
             }
         });
     }
     updatePresence(updates) {
-        if (this.disconnecting) {
+        if (this.phase.kind === "closing") {
             return;
         }
         const socket = this.connection?.socket;

package/dist/pi-intercom/broker/connection.d.ts

@@ -7,22 +7,20 @@ interface ConnectionHandlers {
 }
 /** One socket owns registration, read/error listeners, and graceful shutdown. */
 export declare class BrokerConnection {
-    private registered;
-    private closing;
+    private phase;
     private failure;
-    private registration;
-    private registrationTimer;
     private readonly reader;
     readonly socket: net.Socket;
     private readonly handlers;
     constructor(socket: net.Socket, handlers: ConnectionHandlers);
     start(registration: unknown): Promise<void>;
     confirmRegistration(): void;
-    private clearRegistration;
+    private takeRegistration;
     private failRegistration;
     private protocolError;
     private readonly onError;
     private readonly onClose;
+    private get registered();
     isActive(): boolean;
     disconnect(): Promise<void>;
 }

package/dist/pi-intercom/broker/connection.js

@@ -34,11 +34,8 @@ export async function connectBrokerSocket() {
 }
 /** One socket owns registration, read/error listeners, and graceful shutdown. */
 export class BrokerConnection {
-    registered = false;
-    closing = false;
+    phase = { kind: "acquired" };
     failure = null;
-    registration = null;
-    registrationTimer = null;
     reader;
     socket;
     handlers;
@@ -52,9 +49,9 @@ export class BrokerConnection {
     }
     start(registration) {
         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);
             }
@@ -64,21 +61,26 @@ export class BrokerConnection {
         });
     }
     confirmRegistration() {
-        this.registered = true;
-        const pending = this.registration;
-        this.clearRegistration();
-        pending?.resolve();
+        const pending = this.takeRegistration();
+        if (pending !== undefined) {
+            this.phase = { kind: "active" };
+            pending.resolve();
+        }
     }
-    clearRegistration() {
-        if (this.registrationTimer) {
-            clearTimeout(this.registrationTimer);
+    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;
     }
     failRegistration(error) {
-        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);
@@ -102,31 +104,37 @@ export class BrokerConnection {
         this.handlers.error(error);
     };
     onClose = () => {
-        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);
     };
+    get registered() {
+        return this.phase.kind === "active" || (this.phase.kind === "closing" && this.phase.registered);
+    }
     isActive() {
-        return (this.registered &&
-            !this.closing &&
+        return (this.phase.kind === "active" &&
             !this.socket.destroyed &&
             !this.socket.writableEnded &&
             this.socket.writable);
     }
     disconnect() {
-        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((resolve) => {
             const finish = () => {
-                if (settled) {
-                    return;
-                }
-                settled = true;
                 clearTimeout(timeout);
                 this.socket.off("close", finish);
                 this.socket.off("error", onError);
@@ -140,13 +148,20 @@ 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/dist/pi-intercom/broker/framing.d.ts

@@ -12,6 +12,6 @@ export declare function writeFrame(socket: Socket, json: string, limit?: number)
 /**
  * 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 declare function createMessageReader(onMessage: (msg: unknown) => void, onError: (error: Readonly<Error>) => void, limit?: number): (data: Buffer) => void;

package/dist/pi-intercom/broker/framing.js

@@ -84,33 +84,40 @@ class MessageBuffer {
 /**
  * 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, onError, limit = MAX_FRAME_SIZE_BYTES) {
     const buffer = new MessageBuffer();
-    let length;
+    let state = { kind: "header" };
+    const fail = (error) => {
+        state = { kind: "failed" };
+        buffer.clear();
+        onError(error);
+    };
     return (data) => {
+        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;
             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;
             }
             try {
@@ -118,7 +125,7 @@ export function createMessageReader(onMessage, onError, limit = MAX_FRAME_SIZE_B
             }
             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/dist/pi-intercom/broker/pending-requests.d.ts

@@ -0,0 +1,12 @@
+interface Request {
+    readonly reject: (error: Readonly<Error>) => void;
+}
+/** Map membership owns settlement; taking a request also releases its deadline. */
+export declare class PendingRequests<T extends Request> {
+    private readonly pending;
+    get(id: string): T | undefined;
+    set(id: string, value: T, timeoutMs: number, timeoutError: () => Error): void;
+    take(id: string): T | undefined;
+    fail(error: Readonly<Error>): void;
+}
+export {};

package/dist/pi-intercom/broker/pending-requests.js

@@ -0,0 +1,26 @@
+/** Map membership owns settlement; taking a request also releases its deadline. */
+export class PendingRequests {
+    pending = new Map();
+    get(id) {
+        return this.pending.get(id)?.value;
+    }
+    set(id, value, timeoutMs, timeoutError) {
+        const timer = setTimeout(() => this.take(id)?.reject(timeoutError()), timeoutMs);
+        timer.unref();
+        this.pending.set(id, { value, timer });
+    }
+    take(id) {
+        const pending = this.pending.get(id);
+        if (pending === undefined) {
+            return;
+        }
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        return pending.value;
+    }
+    fail(error) {
+        for (const id of this.pending.keys()) {
+            this.take(id)?.reject(error);
+        }
+    }
+}

package/dist/pi-intercom/broker/replace-deliveries.js

@@ -0,0 +1,38 @@
+const REPLACE_DELIVERY_DELAY_MS = 1500;
+/** Only broker-staged messages remain replaceable; forwarding ends this owner's authority. */
+export class ReplaceDeliveries {
+    pending = new Map();
+    deliver;
+    constructor(deliver) {
+        this.deliver = deliver;
+    }
+    stage(fromId, toId, from, message) {
+        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 });
+    }
+    take(key) {
+        const pending = this.pending.get(key);
+        if (pending !== undefined) {
+            this.pending.delete(key);
+            clearTimeout(pending.timer);
+        }
+        return pending;
+    }
+    flush(key) {
+        const pending = this.take(key);
+        if (pending !== undefined) {
+            this.deliver(pending.toId, pending.from, pending.message);
+        }
+    }
+    disconnected(sessionId) {
+        for (const [key, pending] of this.pending) {
+            if (pending.toId === sessionId ||
+                (pending.fromId === sessionId && pending.message.expectsReply === true)) {
+                this.take(key);
+            }
+        }
+    }
+}

package/dist/pi-intercom/broker/snapshot-reader.d.ts

@@ -1,8 +1,9 @@
 import { type SessionSnapshot } from "../types.ts";
 /** Multipart frames build a private cache; only a complete validated snapshot escapes. */
 export declare class SnapshotReader {
-    private readonly sessions;
-    private readonly receipts;
+    private phase;
+    private open;
+    fail(): void;
     private addSession;
     append(sessions: readonly unknown[], receipts: unknown): void;
     finish(): SessionSnapshot;