@fitchmultz/pi-subagents 0.50.0 → 0.51.0

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

@@ -7,9 +7,10 @@ import { getBrokerRuntimeDir, prepareBrokerSocketPath } from "./paths.js";
 import { brokerPidRecord } from "./pid.js";
 import { assertBrokerCanStart } from "./spawn.js";
 import { LastMessageRelay } from "./last.js";
-import { assertMainParent, canSeeSession, findSessions } from "./targets.js";
-import { acceptBrokerConnection } from "./server-connection.js";
-import { compactTopicMessage, isSessionRegistration, normalizeMessage, normalizeSessionInfo, } from "../types.js";
+import { canSeeSession, findSessions } from "./targets.js";
+import { acceptBrokerConnection, registeredSessionInfo } from "./server-connection.js";
+import { guardedDeliveryError } from "./guard.js";
+import { compactTopicMessage, normalizeMessage, normalizeSessionInfo, } from "../types.js";
 import { errorMessage, isRecord } from "../../shared/unknown.js";
 import { messageSender, snapshotFrames, TopicSnapshot, publicationMessage, deliveryAcknowledgement, shouldReplaceDelivery, } from "./snapshots.js";
 const PID_PATH = join(getBrokerRuntimeDir(), "broker.pid");
@@ -106,15 +107,8 @@ class IntercomBroker {
         }
     }
     register(socket, msg, setId) {
-        if (!isSessionRegistration(msg.session)) {
-            throw new Error("Invalid register message");
-        }
-        assertMainParent(msg.session, this.sessions);
-        const requestedId = typeof msg.requestedId === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(msg.requestedId)
-            ? msg.requestedId
-            : undefined;
-        const id = requestedId !== undefined && !this.sessions.has(requestedId) ? requestedId : randomUUID();
-        const info = { ...msg.session, id, lastSeen: msg.session.lastSeen ?? Date.now() };
+        const info = registeredSessionInfo(msg, this.sessions);
+        const id = info.id;
         snapshotFrames(randomUUID(), [info], true);
         const topicFrames = msg.topicFrames === true;
         this.sessions.set(id, {
@@ -123,6 +117,7 @@ class IntercomBroker {
             topics: new TopicSnapshot(info),
             topicFrames,
             lastMessages: msg.lastMessages === true,
+            receiptReads: msg.receiptReads === 1,
         });
         setId(id);
         if (this.shutdownTimer) {
@@ -133,6 +128,8 @@ class IntercomBroker {
             type: "registered",
             sessionId: id,
             lastMessages: true,
+            receiptReads: 1,
+            ...(msg.guardedDelivery === 1 ? { guardedDelivery: 1 } : {}),
             ...(topicFrames ? { topicsSupported: true, topicFrames: true } : {}),
         });
     }
@@ -240,6 +237,15 @@ class IntercomBroker {
         const targets = findSessions(this.sessions, msg.to, currentId);
         const target = targets[0];
         if (targets.length === 1) {
+            const guardError = guardedDeliveryError(this.sessions, msg.to, message);
+            if (guardError !== null) {
+                writeMessage(socket, {
+                    type: "delivery_failed",
+                    messageId: message.id,
+                    reason: guardError,
+                });
+                return;
+            }
             const fromSession = this.sessions.get(currentId);
             if (!fromSession) {
                 writeMessage(socket, {
@@ -280,11 +286,15 @@ class IntercomBroker {
             "lastIntercomActivity",
             "subscriptions",
             "topics",
+            "applicationGuard",
         ]) {
             if (msg[key] !== undefined) {
                 update[key] = msg[key];
             }
         }
+        if (msg.applicationGuard === null) {
+            delete update.applicationGuard;
+        }
         const nextInfo = normalizeSessionInfo(update);
         if (!nextInfo) {
             throw new Error("Invalid presence update");
@@ -297,15 +307,7 @@ class IntercomBroker {
     }
     sendToSession(fromId, toId, from, message) {
         const target = this.sessions.get(toId);
-        if (!target) {
-            return {
-                id: message.id,
-                accepted: false,
-                delivered: false,
-                reason: "Recipient disconnected before delivery",
-            };
-        }
-        if (shouldReplaceDelivery(message, target.info)) {
+        if (target && shouldReplaceDelivery(message, target.info)) {
             return this.queueReplaceDelivery(fromId, toId, from, message);
         }
         const reason = this.deliverMessage(toId, from, message);
@@ -373,6 +375,10 @@ class IntercomBroker {
         })?.message ?? null);
     }
     deliverMessage(toId, from, message) {
+        const guardError = guardedDeliveryError(this.sessions, toId, message);
+        if (guardError !== null) {
+            return guardError;
+        }
         const target = this.sessions.get(toId);
         if (!target ||
             target.socket.destroyed ||

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

@@ -0,0 +1,13 @@
+import type net from "node:net";
+import { type UnknownRecord } from "../../shared/unknown.ts";
+import type { LastMessageQuery, LastMessageResult, ReceiptQuery, ReceiptResult } from "../types.ts";
+export declare class LastMessageRequests {
+    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,8 +1,12 @@
 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 { writeMessage } from "./framing.js";
 export class LastMessageRequests {
+    timeoutMs;
+    constructor(timeoutMs) {
+        this.timeoutMs = timeoutMs;
+    }
     pending = new Map();
     fail(error) {
         for (const pending of this.pending.values()) {
@@ -12,7 +16,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,8 +27,16 @@ 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 (!isNativeReadQuery(query)) {
             return Promise.reject(new Error("Invalid last-message query"));
         }
         return new Promise((resolve, reject) => {
@@ -32,7 +44,7 @@ export class LastMessageRequests {
             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.d.ts

@@ -0,0 +1,60 @@
+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 lastMessagesSupported;
+    private receiptReadsSupported;
+    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;
+    disconnect(): Promise<void>;
+    listSessions(): Promise<SessionInfo[]>;
+    last(to: string, query?: LastMessageQuery): Promise<LastMessageResult>;
+    receipt(to: string, query: ReceiptQuery): Promise<ReceiptResult>;
+    private readSocket;
+    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

@@ -4,7 +4,7 @@ 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 { isNativeReadQuery, 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). */
@@ -31,7 +31,9 @@ export class IntercomClient extends EventEmitter {
     _sessionId = null;
     _topicsSupported = false;
     lastMessagesSupported = false;
-    lastRequests = new LastMessageRequests();
+    receiptReadsSupported = false;
+    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 &&
@@ -99,6 +105,8 @@ export class IntercomClient extends EventEmitter {
                     this._sessionId = null;
                     this._topicsSupported = false;
                     this.lastMessagesSupported = false;
+                    this.receiptReadsSupported = false;
+                    this.guardedDeliverySupported = false;
                     this.disconnecting = false;
                     this.failPending(error);
                     if (established && !expected) {
@@ -115,6 +123,8 @@ export class IntercomClient extends EventEmitter {
                     requestedId,
                     topicFrames: true,
                     lastMessages: true,
+                    receiptReads: 1,
+                    guardedDelivery: 1,
                 });
             }
             catch (error) {
@@ -193,12 +203,14 @@ export class IntercomClient extends EventEmitter {
         this._sessionId = msg.sessionId;
         this._topicsSupported = msg.topicsSupported === true && msg.topicFrames === true;
         this.lastMessagesSupported = msg.lastMessages === true;
+        this.receiptReadsSupported = 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)) {
+        if (typeof msg.requestId !== "string" || !from || !isNativeReadQuery(msg.query)) {
             throw new Error("Invalid last-message request");
         }
         if (!this.emit("last_request", { requestId: msg.requestId, from, query: msg.query })) {
@@ -269,20 +281,24 @@ 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);
+    async last(to, query = {}) {
+        return await this.lastRequests.last(this.readSocket(query), to, query);
+    }
+    async receipt(to, query) {
+        return await this.lastRequests.receipt(this.readSocket(query), to, query);
+    }
+    readSocket(query) {
+        const socket = this.requireActiveSocket();
+        if (!this.lastMessagesSupported) {
+            throw new Error("This broker does not support last-message reads; reload after it exits.");
         }
-        catch (error) {
-            return Promise.reject(toError(error));
+        if ("messageId" in query && !this.receiptReadsSupported) {
+            throw new Error("publication_unavailable");
         }
+        return socket;
     }
     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 +337,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 +361,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 +398,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,26 @@
+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;
+}
+/** 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>);
+    request(fromId: string, message: UnknownRecord): void;
+    respond(fromId: string, message: UnknownRecord): void;
+    disconnected(sessionId: string): void;
+    private finish;
+}
+export {};