@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/pi-intercom/broker/client-last.d.ts

@@ -0,0 +1,24 @@
+import type net from "node:net";
+import { type UnknownRecord } from "../../shared/unknown.ts";
+import { type NativeReadQuery } from "./last.ts";
+import { type LastMessageQuery, type LastMessageResult, type ReceiptQuery, type ReceiptResult, type SessionInfo } from "../types.ts";
+/** A peer's read of this session or, for a main, of its exited `parked` child. */
+export declare function lastRequest(msg: UnknownRecord): {
+    readonly requestId: string;
+    readonly from: SessionInfo;
+    readonly query: NativeReadQuery;
+    readonly parked?: SessionInfo;
+};
+export declare class LastMessageRequests {
+    /** Negotiated at registration; a failed connection supports neither. */
+    lastMessages: boolean;
+    receiptReads: boolean;
+    private readonly timeoutMs;
+    constructor(timeoutMs: number);
+    private readonly pending;
+    fail(error: Readonly<Error>): void;
+    receive(message: UnknownRecord): void;
+    last(socket: net.Socket, to: string, query: LastMessageQuery): Promise<LastMessageResult>;
+    receipt(socket: net.Socket, to: string, query: ReceiptQuery): Promise<ReceiptResult>;
+    private request;
+}

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

@@ -1,10 +1,33 @@
 import { randomUUID } from "node:crypto";
 import { errorMessage } from "../../shared/unknown.js";
-import { isLastMessageQuery, isLastMessageResult } from "./last.js";
+import { isNativeReadQuery, isNativeReadResult, isLastMessageResult, isReceiptResult, } from "./last.js";
+import { normalizeSessionInfo, } from "../types.js";
 import { writeMessage } from "./framing.js";
+/** A peer's read of this session or, for a main, of its exited `parked` child. */
+export function lastRequest(msg) {
+    const from = normalizeSessionInfo(msg.from);
+    if (typeof msg.requestId !== "string" || !from || !isNativeReadQuery(msg.query)) {
+        throw new Error("Invalid last-message request");
+    }
+    return {
+        requestId: msg.requestId,
+        from,
+        query: msg.query,
+        parked: normalizeSessionInfo(msg.parked) ?? undefined,
+    };
+}
 export class LastMessageRequests {
+    /** Negotiated at registration; a failed connection supports neither. */
+    lastMessages = false;
+    receiptReads = false;
+    timeoutMs;
+    constructor(timeoutMs) {
+        this.timeoutMs = timeoutMs;
+    }
     pending = new Map();
     fail(error) {
+        this.lastMessages = false;
+        this.receiptReads = false;
         for (const pending of this.pending.values()) {
             clearTimeout(pending.timer);
             pending.reject(error);
@@ -12,7 +35,7 @@ export class LastMessageRequests {
         this.pending.clear();
     }
     receive(message) {
-        if (typeof message.requestId !== "string" || !isLastMessageResult(message.result)) {
+        if (typeof message.requestId !== "string" || !isNativeReadResult(message.result)) {
             throw new Error("Invalid last-message response");
         }
         const pending = this.pending.get(message.requestId);
@@ -23,16 +46,30 @@ export class LastMessageRequests {
         this.pending.delete(message.requestId);
         pending.resolve(message.result);
     }
-    request(socket, to, query, timeoutMs) {
-        if (!isLastMessageQuery(query)) {
+    async last(socket, to, query) {
+        const result = await this.request(socket, to, query);
+        return isLastMessageResult(result) ? result : { error: "Invalid last-message response" };
+    }
+    async receipt(socket, to, query) {
+        const result = await this.request(socket, to, query);
+        return isReceiptResult(result) ? result : { error: "Invalid receipt response" };
+    }
+    request(socket, to, query) {
+        if (!this.lastMessages) {
+            return Promise.reject(new Error("This broker does not support last-message reads; reload after it exits."));
+        }
+        if (!isNativeReadQuery(query)) {
             return Promise.reject(new Error("Invalid last-message query"));
         }
+        if ("messageId" in query && !this.receiptReads) {
+            return Promise.reject(new Error("publication_unavailable"));
+        }
         return new Promise((resolve, reject) => {
             const requestId = randomUUID();
             const timer = setTimeout(() => {
                 this.pending.delete(requestId);
                 reject(new Error("Last-message read timeout"));
-            }, timeoutMs);
+            }, this.timeoutMs);
             timer.unref();
             this.pending.set(requestId, { resolve, reject, timer });
             try {

package/dist/pi-intercom/broker/client-park.d.ts

@@ -0,0 +1,9 @@
+import type net from "node:net";
+/** Parking negotiation and its single outstanding broker acknowledgement. */
+export declare class ParkRequests {
+    supported: boolean;
+    private acknowledged?;
+    settle(parked: boolean): void;
+    /** True once the broker retains later input; false when it cannot or the socket closed. */
+    request(socket: () => net.Socket, on: boolean): Promise<boolean>;
+}

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

@@ -0,0 +1,21 @@
+import { writeMessage } from "./framing.js";
+/** Parking negotiation and its single outstanding broker acknowledgement. */
+export class ParkRequests {
+    supported = false;
+    acknowledged;
+    settle(parked) {
+        this.acknowledged?.(parked);
+    }
+    /** True once the broker retains later input; false when it cannot or the socket closed. */
+    request(socket, on) {
+        return new Promise((resolve) => {
+            this.acknowledged = on && this.supported ? resolve : undefined;
+            if (this.supported) {
+                writeMessage(socket(), { type: on ? "park" : "unpark" });
+            }
+            if (this.acknowledged === undefined) {
+                resolve(false);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,59 @@
+import { EventEmitter } from "events";
+import { type SessionInfo, type TopicUpdate, type TopicChange, type SessionSnapshot, type SendResult, type LastMessageQuery, type LastMessageResult, type SendOptions, type ReceiptQuery, type ReceiptResult } from "../types.ts";
+export type { SendResult } from "../types.ts";
+export interface IntercomClientOptions {
+    /** Timeout (ms) for the broker to acknowledge message delivery. */
+    readonly sendTimeoutMs?: number;
+    /** Timeout (ms) for a session list response. */
+    readonly listTimeoutMs?: number;
+}
+export declare class IntercomClient extends EventEmitter {
+    private connection;
+    private _sessionId;
+    private _topicsSupported;
+    private readonly parking;
+    private guardedDeliverySupported;
+    private readonly lastRequests;
+    private readonly pendingSends;
+    private readonly pendingLists;
+    private connecting;
+    private disconnecting;
+    private readonly sendTimeoutMs;
+    private readonly listTimeoutMs;
+    constructor(options?: IntercomClientOptions);
+    private failPending;
+    get sessionId(): string | null;
+    get supportsTopics(): boolean;
+    get supportsGuardedDelivery(): boolean;
+    isConnected(): boolean;
+    private requireActiveSocket;
+    connect(session: Omit<SessionInfo, "id">, requestedId?: string): Promise<void>;
+    private restoreTopics;
+    private handleBrokerMessage;
+    private receiveRegistration;
+    private receiveLastRequest;
+    private receiveMessage;
+    private receiveDelivery;
+    private receiveSessions;
+    park(on?: boolean): Promise<boolean>;
+    disconnect(): Promise<void>;
+    listSessions(): Promise<SessionInfo[]>;
+    last(to: string, query?: LastMessageQuery): Promise<LastMessageResult>;
+    receipt(to: string, query: ReceiptQuery): Promise<ReceiptResult>;
+    respondLast(requestId: string, result: unknown): void;
+    updateTopics(change: TopicChange, onAccepted?: (snapshot: SessionSnapshot) => void): Promise<SessionSnapshot>;
+    private requestSessions;
+    private requireSendSocket;
+    send(to: string, options: SendOptions): Promise<SendResult>;
+    updatePresence(updates: {
+        readonly applicationGuard?: string | null;
+        readonly name?: string;
+        readonly status?: string;
+        readonly model?: string;
+        readonly pendingAsks?: number;
+        readonly acceptsAsks?: boolean;
+        readonly lastIntercomActivity?: number;
+        readonly subscriptions?: SessionInfo["subscriptions"];
+        readonly topics?: readonly TopicUpdate[];
+    }): void;
+}

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

@@ -3,8 +3,9 @@ import { randomUUID } from "crypto";
 import { writeMessage } from "./framing.js";
 import { BrokerConnection, connectBrokerSocket } from "./connection.js";
 import { SnapshotReader } from "./snapshot-reader.js";
-import { LastMessageRequests } from "./client-last.js";
-import { isLastMessageQuery, isLastMessageResult } from "./last.js";
+import { LastMessageRequests, lastRequest } from "./client-last.js";
+import { ParkRequests } from "./client-park.js";
+import { isNativeReadResult } from "./last.js";
 import { errorMessage, isRecord, isUnknownArray, } from "../../shared/unknown.js";
 import { compactTopicMessage, normalizeMessage, normalizeSessionInfo, } from "../types.js";
 /** Default delivery-ack timeout for `send` (broker acknowledges quickly). */
@@ -30,8 +31,9 @@ export class IntercomClient extends EventEmitter {
     connection = null;
     _sessionId = null;
     _topicsSupported = false;
-    lastMessagesSupported = false;
-    lastRequests = new LastMessageRequests();
+    parking = new ParkRequests();
+    guardedDeliverySupported = false;
+    lastRequests;
     pendingSends = new Map();
     pendingLists = new Map();
     connecting = false;
@@ -42,6 +44,7 @@ export class IntercomClient extends EventEmitter {
         super();
         this.sendTimeoutMs = options.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS;
         this.listTimeoutMs = options.listTimeoutMs ?? DEFAULT_LIST_TIMEOUT_MS;
+        this.lastRequests = new LastMessageRequests(this.listTimeoutMs);
     }
     failPending(error) {
         this.lastRequests.fail(error);
@@ -60,6 +63,9 @@ export class IntercomClient extends EventEmitter {
     get supportsTopics() {
         return this.isConnected() && this._topicsSupported;
     }
+    get supportsGuardedDelivery() {
+        return this.isConnected() && this.guardedDeliverySupported;
+    }
     isConnected() {
         return ((this._sessionId ?? "").length > 0 &&
             !this.disconnecting &&
@@ -98,7 +104,8 @@ export class IntercomClient extends EventEmitter {
                     this.connection = null;
                     this._sessionId = null;
                     this._topicsSupported = false;
-                    this.lastMessagesSupported = false;
+                    this.parking.settle(false);
+                    this.guardedDeliverySupported = false;
                     this.disconnecting = false;
                     this.failPending(error);
                     if (established && !expected) {
@@ -115,6 +122,9 @@ export class IntercomClient extends EventEmitter {
                     requestedId,
                     topicFrames: true,
                     lastMessages: true,
+                    parking: true,
+                    receiptReads: 1,
+                    guardedDelivery: 1,
                 });
             }
             catch (error) {
@@ -173,11 +183,15 @@ export class IntercomClient extends EventEmitter {
             case "delivery_failed":
                 this.receiveDelivery(brokerMessage);
                 break;
+            case "parked":
+                this.parking.settle(true);
+                break;
+            case "wake":
             case "session_left":
                 if (typeof brokerMessage.sessionId !== "string") {
-                    throw new Error("Invalid session_left message");
+                    throw new Error(`Invalid ${type} message`);
                 }
-                this.emit("session_left", brokerMessage.sessionId);
+                this.emit(type, brokerMessage.sessionId);
                 break;
             default:
                 throw new Error(`Unknown broker message type: ${type}`);
@@ -192,17 +206,17 @@ export class IntercomClient extends EventEmitter {
         }
         this._sessionId = msg.sessionId;
         this._topicsSupported = msg.topicsSupported === true && msg.topicFrames === true;
-        this.lastMessagesSupported = msg.lastMessages === true;
+        this.lastRequests.lastMessages = msg.lastMessages === true;
+        this.parking.supported = msg.parking === true;
+        this.lastRequests.receiptReads = msg.receiptReads === 1;
+        this.guardedDeliverySupported = msg.guardedDelivery === 1;
         this.connection?.confirmRegistration();
         this.emit("_registered", { type: "registered", sessionId: msg.sessionId });
     }
     receiveLastRequest(msg) {
-        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." });
+        const request = lastRequest(msg);
+        if (!this.emit("last_request", request)) {
+            this.respondLast(request.requestId, { error: "Recipient has no last-message reader." });
         }
     }
     receiveMessage(msg) {
@@ -257,6 +271,9 @@ export class IntercomClient extends EventEmitter {
             pending.resolve(pending.reader.finish());
         }
     }
+    park(on = true) {
+        return this.parking.request(() => this.requireActiveSocket(), on);
+    }
     async disconnect() {
         const connection = this.connection;
         if (!connection) {
@@ -269,20 +286,14 @@ export class IntercomClient extends EventEmitter {
     listSessions() {
         return this.requestSessions().then((snapshot) => [...snapshot.sessions]);
     }
-    last(to, query = {}) {
-        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));
-        }
+    async last(to, query = {}) {
+        return await this.lastRequests.last(this.requireActiveSocket(), to, query);
+    }
+    async receipt(to, query) {
+        return await this.lastRequests.receipt(this.requireActiveSocket(), to, query);
     }
     respondLast(requestId, result) {
-        if (!isLastMessageResult(result)) {
+        if (!isNativeReadResult(result)) {
             throw new Error("Invalid last-message result");
         }
         writeMessage(this.requireActiveSocket(), { type: "last_response", requestId, result });
@@ -321,7 +332,7 @@ export class IntercomClient extends EventEmitter {
             const timeout = setTimeout(() => {
                 if (this.pendingLists.has(requestId)) {
                     this.pendingLists.delete(requestId);
-                    wrappedReject(new Error("List sessions timeout"));
+                    wrappedReject(Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }));
                 }
             }, this.listTimeoutMs);
             timeout.unref();
@@ -345,20 +356,32 @@ export class IntercomClient extends EventEmitter {
             }
         });
     }
+    requireSendSocket(options) {
+        const socket = this.requireActiveSocket();
+        if (options.guard && !this.guardedDeliverySupported) {
+            throw new Error("This broker does not support guarded delivery; no message sent.");
+        }
+        return socket;
+    }
     send(to, options) {
         let socket;
         try {
-            socket = this.requireActiveSocket();
+            socket = this.requireSendSocket(options);
         }
         catch (error) {
             return Promise.reject(toError(error));
         }
-        const messageId = options.messageId ?? randomUUID();
+        const messageId = options.messageId ?? (options.guard ? "" : randomUUID());
+        if (this.pendingSends.has(messageId)) {
+            return Promise.reject(new Error("Message ID already has a pending send"));
+        }
         const message = {
             id: messageId,
             timestamp: Date.now(),
             replyTo: options.replyTo,
             expectsReply: options.expectsReply,
+            guard: options.guard,
+            replyHint: options.replyHint,
             ...(options.human ? { human: options.human } : {}),
             ...(options.topic ? { topic: options.topic } : {}),
             delivery: messageDelivery(options),
@@ -370,6 +393,9 @@ export class IntercomClient extends EventEmitter {
                 attachments: options.attachments,
             },
         };
+        if ((options.guard || options.replyHint) && normalizeMessage(message) === null) {
+            return Promise.reject(new Error("Invalid message format"));
+        }
         return new Promise((resolve, reject) => {
             const wrappedResolve = (result) => {
                 clearTimeout(timeout);

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

@@ -0,0 +1,29 @@
+import net from "node:net";
+export declare function connectBrokerSocket(): Promise<net.Socket>;
+interface ConnectionHandlers {
+    readonly message: (message: unknown) => void;
+    readonly error: (error: Readonly<Error>) => void;
+    readonly closed: (error: Readonly<Error>, expected: boolean) => void;
+}
+/** One socket owns registration, read/error listeners, and graceful shutdown. */
+export declare class BrokerConnection {
+    private registered;
+    private closing;
+    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 failRegistration;
+    private protocolError;
+    private readonly onError;
+    private readonly onClose;
+    isActive(): boolean;
+    disconnect(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,17 @@
+import type { Socket } from "net";
+export declare const MAX_FRAME_SIZE_BYTES: number;
+export declare function intercomMessageSizeBytes(msg: unknown): number;
+export declare function validateIntercomMessageSize(msg: unknown): Error | null;
+/**
+ * Write a length-prefixed message to a socket.
+ * Format: 4-byte big-endian length + JSON payload
+ */
+export declare function writeMessage(socket: Socket, msg: unknown): void;
+/** Write serialized JSON; false means Node accepted it but the caller should wait for drain. */
+export declare function writeFrame(socket: Socket, json: string, limit?: number): boolean;
+/**
+ * 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.
+ */
+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

@@ -14,15 +14,18 @@ export function validateIntercomMessageSize(msg) {
  * Format: 4-byte big-endian length + JSON payload
  */
 export function writeMessage(socket, msg) {
-    const json = JSON.stringify(msg);
+    writeFrame(socket, JSON.stringify(msg));
+}
+/** Write serialized JSON; false means Node accepted it but the caller should wait for drain. */
+export function writeFrame(socket, json, limit = MAX_FRAME_SIZE_BYTES) {
     const size = Buffer.byteLength(json, "utf-8");
-    if (size > MAX_FRAME_SIZE_BYTES) {
-        throw new Error(`Intercom message too large (${size} bytes; max ${MAX_FRAME_SIZE_BYTES})`);
+    if (size > limit) {
+        throw new Error(`Intercom message too large (${size} bytes; max ${limit})`);
     }
     const payload = Buffer.from(json, "utf-8");
     const header = Buffer.alloc(4);
     header.writeUInt32BE(payload.length, 0);
-    socket.write(Buffer.concat([header, payload]));
+    return socket.write(Buffer.concat([header, payload]));
 }
 /** Retain fragments until a header or payload is complete; copy each fragmented value once. */
 class MessageBuffer {
@@ -77,7 +80,7 @@ class MessageBuffer {
  * Calls onMessage for each complete message received.
  * Protocol or handler errors are reported to onError so the caller can close the socket.
  */
-export function createMessageReader(onMessage, onError) {
+export function createMessageReader(onMessage, onError, limit = MAX_FRAME_SIZE_BYTES) {
     const buffer = new MessageBuffer();
     let length;
     return (data) => {
@@ -85,8 +88,8 @@ export function createMessageReader(onMessage, onError) {
         while (buffer.length >= (length ?? 4)) {
             if (length === undefined) {
                 length = buffer.read(4).readUInt32BE(0);
-                if (length > MAX_FRAME_SIZE_BYTES) {
-                    onError(new Error(`Intercom frame too large (${length} bytes; max ${MAX_FRAME_SIZE_BYTES})`));
+                if (length > limit) {
+                    onError(new Error(`Intercom frame too large (${length} bytes; max ${limit})`));
                     buffer.clear();
                     length = undefined;
                     return;

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

@@ -0,0 +1,23 @@
+/** Guarded commands use an exact main, never convenience names or a replacement context. */
+export function guardedDeliveryError(sessions, to, message) {
+    const guard = message.guard;
+    if (!guard) {
+        return null;
+    }
+    const registered = sessions.get(to);
+    if (!registered || to !== guard.peerId) {
+        return "Guarded target not found";
+    }
+    const target = registered.info;
+    if (target.guardedDelivery !== 1) {
+        return "Recipient does not support guarded delivery";
+    }
+    if (target.parentSessionId !== undefined ||
+        target.rootSessionId !== guard.rootSessionId ||
+        target.incarnation !== guard.incarnation ||
+        target.applicationGuard !== guard.applicationGuard) {
+        return "Guarded target changed";
+    }
+    const mains = [...sessions.values()].filter(({ info }) => info.rootSessionId === guard.rootSessionId && info.parentSessionId === undefined);
+    return mains.length === 1 ? null : "Guarded root is ambiguous";
+}

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

@@ -0,0 +1,30 @@
+import type net from "node:net";
+import { type UnknownRecord } from "../../shared/unknown.ts";
+import { type LastMessageQuery, type LastMessageResult, type SessionInfo, type ReceiptQuery, type ReceiptResult } from "../types.ts";
+export type NativeReadQuery = LastMessageQuery | ReceiptQuery;
+export type NativeReadResult = LastMessageResult | ReceiptResult;
+export declare function isNativeReadQuery(value: unknown): value is NativeReadQuery;
+export declare function isReceiptResult(value: unknown): value is ReceiptResult;
+export declare function isNativeReadResult(value: unknown): value is NativeReadResult;
+export declare function isLastMessageResult(value: unknown): value is LastMessageResult;
+interface LastPeer {
+    readonly socket: net.Socket;
+    readonly info: SessionInfo;
+    readonly lastMessages: boolean;
+    readonly receiptReads: boolean;
+    readonly parked?: {
+        readonly closed: boolean;
+    };
+}
+/** Correlation belongs to the broker, not the requester or the recipient's model queue. */
+export declare class LastMessageRelay {
+    private readonly pending;
+    private readonly sessions;
+    constructor(sessions: ReadonlyMap<string, LastPeer>);
+    /** `reader` names another peer that answers for an exited target from its captured history. */
+    request(fromId: string, input: UnknownRecord, reader: (id: string) => LastPeer | undefined): void;
+    respond(fromId: string, message: UnknownRecord): void;
+    disconnected(sessionId: string): void;
+    private finish;
+}
+export {};