@fitchmultz/pi-subagents 0.44.7 → 0.46.0

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

@@ -0,0 +1,165 @@
+import net from "node:net";
+import { errorMessage } from "../../shared/unknown.js";
+import { getBrokerSocketPath, getLegacyBrokerSocketPath, isOwnedBrokerSocket } from "./paths.js";
+import { createMessageReader, writeMessage } from "./framing.js";
+function connectSocket(socketPath, timeoutMs = 500) {
+    return new Promise((resolve, reject) => {
+        const socket = net.connect(socketPath);
+        const finish = (error) => {
+            clearTimeout(timeout);
+            socket.off("connect", onConnect);
+            socket.off("error", onError);
+            if (error) {
+                socket.destroy();
+                reject(error);
+            }
+            else {
+                resolve(socket);
+            }
+        };
+        const onConnect = () => finish();
+        const onError = (error) => finish(error);
+        socket.once("connect", onConnect);
+        socket.once("error", onError);
+        const timeout = setTimeout(() => finish(new Error(`Connection timeout: ${socketPath}`)), timeoutMs);
+        timeout.unref();
+    });
+}
+export async function connectBrokerSocket() {
+    const preferred = getBrokerSocketPath();
+    const legacy = getLegacyBrokerSocketPath();
+    const candidates = [preferred, ...(legacy !== preferred ? [legacy] : [])];
+    let lastError;
+    for (const candidate of candidates) {
+        if (!isOwnedBrokerSocket(candidate)) {
+            continue;
+        }
+        try {
+            // Preferred and legacy sockets must be tried in order, never connected concurrently.
+            // oxlint-disable-next-line no-await-in-loop
+            return await connectSocket(candidate);
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(errorMessage(error));
+        }
+    }
+    throw lastError ?? new Error(`Intercom broker socket is unavailable: ${preferred}`);
+}
+/** One socket owns registration, read/error listeners, and graceful shutdown. */
+export class BrokerConnection {
+    registered = false;
+    closing = false;
+    failure = null;
+    registration = null;
+    registrationTimer = null;
+    reader;
+    socket;
+    handlers;
+    constructor(socket, handlers) {
+        this.socket = socket;
+        this.handlers = handlers;
+        this.reader = createMessageReader(handlers.message, (error) => this.protocolError(error));
+        socket.on("data", this.reader);
+        socket.on("error", this.onError);
+        socket.on("close", this.onClose);
+    }
+    start(registration) {
+        return new Promise((resolve, reject) => {
+            this.registration = { resolve, reject };
+            this.registrationTimer = setTimeout(() => this.failRegistration(new Error("Connection timeout")), 10000);
+            this.registrationTimer.unref();
+            try {
+                writeMessage(this.socket, registration);
+            }
+            catch (error) {
+                this.failRegistration(error instanceof Error ? error : new Error(errorMessage(error)));
+            }
+        });
+    }
+    confirmRegistration() {
+        this.registered = true;
+        const pending = this.registration;
+        this.clearRegistration();
+        pending?.resolve();
+    }
+    clearRegistration() {
+        if (this.registrationTimer) {
+            clearTimeout(this.registrationTimer);
+        }
+        this.registrationTimer = null;
+        this.registration = null;
+    }
+    failRegistration(error) {
+        const pending = this.registration;
+        this.clearRegistration();
+        this.failure = error;
+        this.socket.destroy();
+        pending?.reject(error);
+    }
+    protocolError(error) {
+        const failure = new Error(`Intercom protocol error: ${error.message}`, { cause: error });
+        if (!this.registered) {
+            this.failRegistration(failure);
+            return;
+        }
+        this.failure = failure;
+        this.handlers.error(failure);
+        this.socket.destroy();
+    }
+    onError = (error) => {
+        if (!this.registered) {
+            this.failRegistration(error);
+            return;
+        }
+        this.failure = error;
+        this.handlers.error(error);
+    };
+    onClose = () => {
+        const pending = this.registration;
+        this.clearRegistration();
+        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);
+    };
+    isActive() {
+        return (this.registered &&
+            !this.closing &&
+            !this.socket.destroyed &&
+            !this.socket.writableEnded &&
+            this.socket.writable);
+    }
+    disconnect() {
+        this.closing = true;
+        this.failure = null;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeout);
+                this.socket.off("close", finish);
+                this.socket.off("error", onError);
+                resolve();
+            };
+            const onError = () => {
+                this.socket.destroy();
+            };
+            const timeout = setTimeout(() => {
+                this.socket.destroy();
+            }, 2000);
+            this.socket.once("close", finish);
+            this.socket.once("error", onError);
+            try {
+                writeMessage(this.socket, { type: "unregister" });
+                this.socket.end();
+            }
+            catch {
+                this.socket.destroy();
+            }
+        });
+    }
+}

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

@@ -1,3 +1,4 @@
+import { errorMessage } from "../../shared/unknown.js";
 export const MAX_FRAME_SIZE_BYTES = 1024 * 1024;
 export function intercomMessageSizeBytes(msg) {
     return Buffer.byteLength(JSON.stringify(msg), "utf-8");
@@ -14,8 +15,9 @@ export function validateIntercomMessageSize(msg) {
  */
 export function writeMessage(socket, msg) {
     const tooLarge = validateIntercomMessageSize(msg);
-    if (tooLarge)
+    if (tooLarge) {
         throw tooLarge;
+    }
     const json = JSON.stringify(msg);
     const payload = Buffer.from(json, "utf-8");
     const header = Buffer.alloc(4);
@@ -48,7 +50,7 @@ export function createMessageReader(onMessage, onError) {
                 msg = JSON.parse(payload.toString("utf-8"));
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = errorMessage(error);
                 onError(new Error(`Failed to parse intercom message: ${message}`, { cause: error }));
                 return;
             }
@@ -56,7 +58,7 @@ export function createMessageReader(onMessage, onError) {
                 onMessage(msg);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = errorMessage(error);
                 onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
                 return;
             }

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

@@ -5,7 +5,10 @@ import { dirname, join } from "node:path";
 import { getPiAgentDir } from "../agent-dir.js";
 const MAX_UNIX_SOCKET_PATH_BYTES = 100;
 function agentDigest(agentDir, uid) {
-    return createHash("sha256").update(uid === undefined ? agentDir : `${uid}:${agentDir}`).digest("hex").slice(0, 16);
+    return createHash("sha256")
+        .update(uid === undefined ? agentDir : `${uid}:${agentDir}`)
+        .digest("hex")
+        .slice(0, 16);
 }
 export function getLegacyBrokerSocketPath(agentDir = getPiAgentDir()) {
     return join(tmpdir(), `pi-intercom-${agentDigest(agentDir)}.sock`);

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

@@ -2,65 +2,93 @@ import { closeSync, openSync, readFileSync, readlinkSync } from "node:fs";
 // Keep the first numeric line readable by older brokers/spawn guards.
 // starttime is /proc/<pid>/stat field 22, in clock ticks; never round it to Number.
 const IDENTITY = /^linux-v1 ([0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}) (pid:\[\d+\]) (time:\[\d+\]) (\d+)$/;
+function processIdentity(base, pid) {
+    const stat = readFileSync(`${base}/stat`, "utf8");
+    // comm can contain spaces, newlines and ')'; fields after its final ')' are fixed.
+    if (!stat.startsWith(`${pid} (`)) {
+        return;
+    }
+    const startTicks = stat
+        .slice(stat.lastIndexOf(")") + 2)
+        .split(/\s+/)
+        .at(19);
+    if (startTicks === undefined) {
+        return;
+    }
+    const bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    const pidNamespace = readlinkSync(`${base}/ns/pid`);
+    // Linux applies the reader's time-namespace offset to stat.starttime.
+    const timeNamespace = readlinkSync("/proc/self/ns/time");
+    const identity = `linux-v1 ${bootId} ${pidNamespace} ${timeNamespace} ${startTicks}`;
+    return IDENTITY.test(identity) ? identity : undefined;
+}
+function threadGroupLeader(status, pid) {
+    const tgid = Number(/^Tgid:[ \t]+(\d+)$/m.exec(status)?.[1]);
+    if (!Number.isSafeInteger(tgid) ||
+        tgid <= 0 ||
+        Number(/^Pid:[ \t]+(\d+)$/m.exec(status)?.[1]) !== pid) {
+        return;
+    }
+    return tgid;
+}
 export function readLinuxProcess(pid) {
-    if (process.platform !== "linux")
+    if (process.platform !== "linux") {
         return undefined;
+    }
     let fd;
     try {
         // A procfs mounted from an ancestor PID namespace has different PID numbers
         // from kill(2)/process.pid. Do not use that view to disprove broker identity.
         const self = readFileSync("/proc/self/status", "utf8");
-        if (!new RegExp(`^NStgid:[ \\t]+${process.pid}$`, "m").test(self))
+        if (!new RegExp(`^NStgid:[ \\t]+${process.pid}$`, "m").test(self)) {
             return undefined;
+        }
         // Pin this proc directory so separate metadata reads cannot cross PID reuse.
         fd = openSync(`/proc/${pid}`, "r");
         const base = `/proc/self/fd/${fd}`;
         const status = readFileSync(`${base}/status`, "utf8");
-        const tgid = Number(/^Tgid:[ \t]+(\d+)$/m.exec(status)?.[1]);
-        if (!Number.isSafeInteger(tgid) || tgid <= 0
-            || Number(/^Pid:[ \t]+(\d+)$/m.exec(status)?.[1]) !== pid)
-            return undefined;
+        const tgid = threadGroupLeader(status, pid);
+        if (tgid === undefined) {
+            return;
+        }
         // Node writes process.pid (the thread-group leader), never a worker TID.
-        if (tgid !== pid)
+        if (tgid !== pid) {
             return { tgid };
-        const stat = readFileSync(`${base}/stat`, "utf8");
-        // comm can contain spaces, newlines and ')'; fields after its final ')' are fixed.
-        if (!stat.startsWith(`${pid} (`))
-            return undefined;
-        const startTicks = stat.slice(stat.lastIndexOf(")") + 2).split(/\s+/)[19];
-        const bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
-        const pidNamespace = readlinkSync(`${base}/ns/pid`);
-        // Linux applies the *reader's* time-namespace offset to stat.starttime.
-        const timeNamespace = readlinkSync("/proc/self/ns/time");
-        const identity = `linux-v1 ${bootId} ${pidNamespace} ${timeNamespace} ${startTicks}`;
-        return IDENTITY.test(identity) ? { tgid, identity } : undefined;
+        }
+        const identity = processIdentity(base, pid);
+        return identity !== undefined ? { tgid, identity } : undefined;
     }
     catch {
         // Unavailable procfs, permissions or incomplete observations prove nothing.
         return undefined;
     }
     finally {
-        if (fd !== undefined)
+        if (fd !== undefined) {
             closeSync(fd);
+        }
     }
 }
 export function brokerPidRecord() {
     const identity = readLinuxProcess(process.pid)?.identity;
-    return `${process.pid}\n${identity ? `${identity}\n` : ""}`;
+    return `${process.pid}\n${identity !== undefined ? `${identity}\n` : ""}`;
 }
 export function isBrokerPidReused(pid, record) {
     const current = readLinuxProcess(pid);
-    if (!current)
+    if (!current) {
         return false;
-    if (current.tgid !== pid)
+    }
+    if (current.tgid !== pid) {
         return true;
+    }
     const saved = IDENTITY.exec(record.slice(record.indexOf("\n") + 1).trim());
     const actual = IDENTITY.exec(current.identity ?? "");
-    if (!saved || !actual)
+    if (!saved || !actual) {
         return false;
+    }
     const [, boot, namespace, clock, start] = saved;
     const [, actualBoot, actualNamespace, actualClock, actualStart] = actual;
     // A clock-namespace change alone is not evidence that the process changed.
-    return boot !== actualBoot || namespace !== actualNamespace
-        || (clock === actualClock && start !== actualStart);
+    return (boot !== actualBoot ||
+        namespace !== actualNamespace ||
+        (clock === actualClock && start !== actualStart));
 }

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

@@ -0,0 +1,78 @@
+import { isRecord, isUnknownArray } from "../../shared/unknown.js";
+import { normalizeSessionInfo } from "../types.js";
+function optionalReceiptFields(value) {
+    if ((value.queued !== undefined && typeof value.queued !== "boolean") ||
+        (value.reason !== undefined && typeof value.reason !== "string")) {
+        throw new Error("Invalid topic delivery receipts");
+    }
+    return {
+        ...(typeof value.queued === "boolean" ? { queued: value.queued } : {}),
+        ...(typeof value.reason === "string" ? { reason: value.reason } : {}),
+    };
+}
+function optionalArray(value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isUnknownArray(value)) {
+        throw new Error("Invalid session snapshot row");
+    }
+    return value;
+}
+function receipt(value) {
+    if (!isRecord(value) ||
+        typeof value.to !== "string" ||
+        typeof value.id !== "string" ||
+        typeof value.accepted !== "boolean" ||
+        typeof value.delivered !== "boolean") {
+        throw new Error("Invalid topic delivery receipts");
+    }
+    const optional = optionalReceiptFields(value);
+    return {
+        to: value.to,
+        id: value.id,
+        accepted: value.accepted,
+        delivered: value.delivered,
+        ...optional,
+    };
+}
+/** Multipart frames build a private cache; only a complete validated snapshot escapes. */
+export class SnapshotReader {
+    sessions = new Map();
+    receipts = [];
+    addSession(row) {
+        if (!isRecord(row) || typeof row.id !== "string") {
+            throw new Error("Invalid session snapshot row");
+        }
+        const topics = optionalArray(row.topics);
+        const subscriptions = optionalArray(row.subscriptions);
+        const previous = this.sessions.get(row.id);
+        const info = normalizeSessionInfo({
+            ...previous,
+            ...row,
+            ...(topics !== undefined ? { topics: [...(previous?.topics ?? []), ...topics] } : {}),
+            ...(subscriptions !== undefined
+                ? { subscriptions: [...(previous?.subscriptions ?? []), ...subscriptions] }
+                : {}),
+        });
+        if (!info) {
+            throw new Error("Invalid session snapshot");
+        }
+        this.sessions.set(info.id, info);
+    }
+    append(sessions, receipts) {
+        for (const row of sessions) {
+            this.addSession(row);
+        }
+        if (receipts === undefined) {
+            return;
+        }
+        if (!isUnknownArray(receipts)) {
+            throw new Error("Invalid topic delivery receipts");
+        }
+        this.receipts.push(...receipts.map(receipt));
+    }
+    finish() {
+        return { sessions: [...this.sessions.values()], receipts: this.receipts };
+    }
+}

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

@@ -0,0 +1,188 @@
+import { randomUUID } from "node:crypto";
+import { isRecord } from "../../shared/unknown.js";
+import { isTopicUpdate, isTopicSubscription, } from "../types.js";
+import { validateIntercomMessageSize } from "./framing.js";
+/** Direct messages and old clients receive identity, not potentially large topic state. */
+export function messageSender(info) {
+    const { topics: _topics, subscriptions: _subscriptions, ...identity } = info;
+    return identity;
+}
+function topicFrames(requestId, info) {
+    const frames = [
+        {
+            type: "sessions",
+            requestId,
+            sessions: [
+                {
+                    ...messageSender(info),
+                    ...(info.topics ? { topics: [] } : {}),
+                    ...(info.subscriptions ? { subscriptions: [] } : {}),
+                },
+            ],
+            more: true,
+        },
+    ];
+    for (const topic of info.topics ?? []) {
+        frames.push({
+            type: "sessions",
+            requestId,
+            sessions: [{ id: info.id, topics: [topic] }],
+            more: true,
+        });
+    }
+    for (const subscription of info.subscriptions ?? []) {
+        frames.push({
+            type: "sessions",
+            requestId,
+            sessions: [{ id: info.id, subscriptions: [subscription] }],
+            more: true,
+        });
+    }
+    return frames;
+}
+export function snapshotFrames(requestId, infos, stream) {
+    // ponytail: one record per frame; pack records only if measured socket overhead warrants it.
+    const frames = stream
+        ? [
+            ...infos.flatMap((info) => topicFrames(requestId, info)),
+            { type: "sessions", requestId, sessions: [], more: false },
+        ]
+        : [{ type: "sessions", requestId, sessions: infos.map(messageSender) }];
+    for (const frame of frames) {
+        const error = validateIntercomMessageSize(frame);
+        if (error) {
+            throw error;
+        }
+    }
+    return frames;
+}
+function validPublication(topic) {
+    if (!isTopicUpdate(topic) || topic.text.trim().length === 0) {
+        throw new Error("Invalid topic publication");
+    }
+    if (topic.event === "release" &&
+        ((topic.resource ?? "").length === 0 || topic.ownership !== "released")) {
+        throw new Error("Invalid topic publication");
+    }
+    return topic;
+}
+function topicMutation(change) {
+    if (change.action === "publish") {
+        return { kind: "publication", topic: validPublication(change.topic), publish: true };
+    }
+    if (change.action === "restore" && isTopicUpdate(change.topic)) {
+        return { kind: "publication", topic: validPublication(change.topic), publish: false };
+    }
+    if ((change.action === "subscribe" || change.action === "restore") &&
+        isTopicSubscription(change.subscription)) {
+        return { kind: "subscription", subscription: change.subscription };
+    }
+    if (change.action === "unsubscribe" && typeof change.topic === "string") {
+        return { kind: "unsubscribe", topic: change.topic };
+    }
+    throw new Error("Invalid topic change");
+}
+function publicationUpdate(topic, previous, publish) {
+    const revision = publish
+        ? Math.max(previous?.revision ?? 0, topic.revision - 1) + 1
+        : topic.revision;
+    if (!Number.isSafeInteger(revision) || revision <= 0) {
+        throw new Error("Invalid topic revision");
+    }
+    return { ...topic, revision };
+}
+class TopicSnapshot {
+    info;
+    topics;
+    subscriptions;
+    constructor(info) {
+        this.info = info;
+        this.topics = new Map((info.topics ?? []).map((topic) => [topic.topic, topic]));
+        this.subscriptions = new Map((info.subscriptions ?? []).map((entry) => [entry.topic, entry]));
+    }
+    apply(mutation) {
+        switch (mutation.kind) {
+            case "publication": {
+                const previous = this.topics.get(mutation.topic.topic);
+                const update = publicationUpdate(mutation.topic, previous, mutation.publish);
+                if (mutation.publish || (previous?.revision ?? 0) < update.revision) {
+                    this.topics.set(update.topic, update);
+                }
+                if (mutation.publish) {
+                    return update;
+                }
+                return;
+            }
+            case "subscription":
+                this.subscriptions.set(mutation.subscription.topic, mutation.subscription);
+                return;
+            case "unsubscribe":
+                this.subscriptions.delete(mutation.topic);
+                return;
+        }
+    }
+    snapshot(publication) {
+        return {
+            ...this.info,
+            topics: [...this.topics.values()],
+            subscriptions: [...this.subscriptions.values()],
+            ...(publication ? { lastIntercomActivity: Date.now() } : {}),
+        };
+    }
+}
+/** Prepare a change without mutating the usable broker snapshot before frame validation. */
+export function prepareTopicChange(info, change, supported) {
+    if (change === undefined) {
+        return { info, restore: false };
+    }
+    if (!supported || !isRecord(change)) {
+        throw new Error("Topic snapshots unavailable for this client");
+    }
+    const pending = new TopicSnapshot(info);
+    const publication = pending.apply(topicMutation(change));
+    return {
+        info: pending.snapshot(publication),
+        restore: change.action === "restore",
+        ...(publication ? { publication } : {}),
+    };
+}
+export function deliveryAcknowledgement(receipt) {
+    if (!receipt.accepted) {
+        return {
+            type: "delivery_failed",
+            messageId: receipt.id,
+            reason: receipt.reason ?? "Delivery failed",
+        };
+    }
+    if (receipt.queued === true) {
+        return {
+            type: "delivery_queued",
+            messageId: receipt.id,
+            reason: receipt.reason ?? "Queued for replace-mode delivery",
+        };
+    }
+    return { type: "delivered", messageId: receipt.id };
+}
+export function shouldReplaceDelivery(message, info) {
+    if (message.delivery !== "queue" ||
+        message.queueMode !== "replace" ||
+        (message.threadId ?? "").length === 0) {
+        return false;
+    }
+    const status = info.status ?? "";
+    return (message.expectsReply === true ||
+        ((status === "idle" || status.startsWith("idle ")) && info.acceptsAsks !== false));
+}
+export function publicationMessage(publication, awaitRelease) {
+    const urgent = publication.event === "blocker" ||
+        publication.event === "decision" ||
+        (publication.event === "release" && awaitRelease);
+    return {
+        id: randomUUID(),
+        timestamp: Date.now(),
+        topic: publication,
+        content: { text: publication.text },
+        delivery: urgent ? "steer" : "queue",
+        ...(urgent ? {} : { queueMode: "replace", threadId: `topic:${publication.topic}` }),
+    };
+}