@fitchmultz/pi-subagents 0.46.2 → 0.48.0

package/dist/pi-intercom/bridge-session.js

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { IntercomClient } from "./broker/client.js";
-import { formatSessionTarget, resolveSessionProjectId, resolveSessionTarget, } from "./session-targets.js";
-import { Fault, INBOX_BYTES, INBOX_COUNT, cancelled, log, wait } from "./bridge-protocol.js";
+import { resolveSessionProjectId } from "./session-targets.js";
+import { Fault, cancelled, log, wait } from "./bridge-protocol.js";
+import { Mailbox } from "./bridge-mailbox.js";
+import { resolveBridgeTarget, bridgeSessionList } from "./bridge-target.js";
+import { ControlReplies } from "./bridge-control.js";
 import { WaitingAsk } from "./bridge-ask.js";
 const MAX_REQUESTS = 8;
 const IDLE_TIMEOUT = 5 * 60 * 1000;
@@ -17,9 +20,10 @@ export class Session {
         listTimeoutMs: LIST_TIMEOUT,
     });
     requests = new Set();
-    inbox = new Map();
-    inboxBytes = 0;
+    inbox;
+    replying = new Set();
     pending;
+    controls = new ControlReplies();
     closed = false;
     connecting;
     disconnecting;
@@ -30,6 +34,7 @@ export class Session {
         this.owner = owner;
         this.identity = identity;
         this.expires = expires;
+        this.inbox = new Mailbox(owner.stateDir, identity.fingerprint256, owner.notifications);
         this.client.on("error", () => this.close(new Fault(503, "broker_unavailable", "Broker connection failed.")));
         this.client.on("disconnected", () => this.close(new Fault(503, "broker_disconnected", "Broker disconnected.")));
         this.client.on("_registered", () => {
@@ -49,6 +54,9 @@ export class Session {
         if (this.closed) {
             throw this.closeReason;
         }
+        this.authorize();
+    }
+    authorize() {
         if (!this.owner.allowed(this.identity)) {
             throw new Fault(403, "revoked", "Identity is no longer authorized.");
         }
@@ -102,6 +110,7 @@ export class Session {
             this.close(fault);
             throw fault;
         }
+        this.presence();
         log("registered", this.fields());
     }
     async connect(signal) {
@@ -136,42 +145,33 @@ export class Session {
             // The original request receives the connection failure; teardown must still close a late socket.
         }
         await this.disconnect();
+        this.owner.lost(this.identity.fingerprint256, this.inbox.close());
         this.owner.retired(this.identity.fingerprint256, this.generation);
         log("session_closed", { ...this.fields(), result: this.closeReason.code });
     }
-    close(error) {
+    close(fault) {
         if (this.closed) {
             return;
         }
         this.closed = true;
-        this.closeReason = error;
+        this.closeReason = fault;
         clearTimeout(this.lease);
-        this.pending?.reject(error);
+        this.pending?.reject(fault);
+        this.controls.close(fault);
         for (const controller of this.requests) {
-            controller.abort(error);
+            controller.abort(fault);
         }
-        this.owner.lost(this.identity.fingerprint256, this.inbox.size);
-        this.inbox.clear();
-        this.inboxBytes = 0;
         // Retain the generation until acquisition/registration AND final disconnect settle.
-        this.startRetirement();
-    }
-    startRetirement() {
         this.retirement = this.retire().catch((caught) => this.cleanupFailed(caught));
     }
     async settled() {
         await this.retirement;
     }
     peerLeft(id) {
+        this.controls.peerLeft(id);
         if (this.pending?.peer === id && !this.pending.settled) {
             this.pending.reject(new Fault(409, "peer_offline", "Ask recipient disconnected.", { id: this.pending.id }));
         }
-        for (const [messageId, entry] of this.inbox) {
-            if (entry.from.id === id && entry.message.expectsReply === true) {
-                this.remove(messageId);
-                this.owner.lost(this.identity.fingerprint256);
-            }
-        }
         this.presence();
     }
     receive(from, message) {
@@ -187,48 +187,60 @@ export class Session {
                 : new Fault(403, "revoked", "Identity is no longer authorized."));
             return;
         }
-        log("received", { ...this.fields(), peer: from.id, messageId: message.id, result: "received" });
-        const pending = this.pending;
-        if (pending?.matches(from.id, message.replyTo) === true) {
-            pending.resolve({ from, message });
+        if (this.controls.receive(from.id, message)) {
             return;
         }
-        if (this.inbox.has(message.id)) {
-            this.owner.lost(this.identity.fingerprint256);
+        if (!this.inbox.persistent && this.resolveReply(from, message)) {
             return;
         }
-        const bytes = Buffer.byteLength(JSON.stringify({ from, message }));
-        if (this.inbox.size >= INBOX_COUNT || this.inboxBytes + bytes > INBOX_BYTES) {
-            this.owner.lost(this.identity.fingerprint256);
+        this.storeReceive(from, message);
+    }
+    storeReceive(from, message) {
+        let result;
+        try {
+            result = this.inbox.add({ from, message });
+        }
+        catch {
             log("inbox_overflow", {
                 ...this.fields(),
                 peer: from.id,
                 messageId: message.id,
-                result: "lost",
+                result: "storage_failed",
+                lossRecorded: false,
             });
+            this.close(new Fault(507, "mailbox_storage_failed", "Mailbox storage failed; inspect the metadata audit for unrecorded losses."));
             return;
         }
-        // ponytail: bounded volatile inbox; use a private durable journal if restart/lease-loss recovery is required.
-        this.inbox.set(message.id, { from, message, bytes, replying: false });
-        this.inboxBytes += bytes;
+        if (result === "lost" || (result === "duplicate" && !this.inbox.persistent)) {
+            this.owner.lost(this.identity.fingerprint256);
+        }
+        this.recordReceive(from.id, message.id, result);
+        if (result !== "lost") {
+            this.resolveReply(from, message);
+        }
         this.presence();
     }
-    remove(id) {
-        const entry = this.inbox.get(id);
-        if (entry) {
-            this.inboxBytes -= entry.bytes;
-            this.inbox.delete(id);
+    resolveReply(from, message) {
+        const pending = this.pending;
+        if (pending?.matches(from.id, message.replyTo) !== true) {
+            return false;
         }
+        pending.resolve({ from, message });
+        return true;
+    }
+    recordReceive(peer, messageId, result) {
+        log(result === "lost" ? "inbox_overflow" : "received", {
+            ...this.fields(),
+            peer,
+            messageId,
+            result: result === "lost" && this.inbox.persistent ? "storage_failed" : result,
+        });
     }
     presence() {
         if (this.closed) {
             return;
         }
-        const pendingAsks = [...this.inbox.values()].filter((entry) => entry.message.expectsReply === true).length;
-        this.client.updatePresence({
-            pendingAsks,
-            acceptsAsks: this.inbox.size < INBOX_COUNT && this.inboxBytes < INBOX_BYTES,
-        });
+        this.client.updatePresence(this.inbox.presence());
     }
     async peers(signal) {
         this.guard(signal);
@@ -250,20 +262,16 @@ export class Session {
         await this.connect(signal);
         return this.peers(signal);
     }
+    async nativeControl(operation, certificate, context) {
+        await this.connect(context.signal);
+        const peer = await this.target(operation.to, context.signal);
+        return this.controls.request(this.client, { ...operation, peer: peer.id, certificate }, { ...context, guard: () => this.guard(context.signal) });
+    }
     async target(to, signal) {
-        const resolution = resolveSessionTarget(await this.peers(signal), to);
-        if (resolution.status === "none") {
-            throw new Fault(404, "peer_offline", "Peer is not connected.");
-        }
-        if (resolution.status !== "found" || !resolution.target) {
-            throw new Fault(409, "ambiguous_target", "Use an unambiguous peer name or session ID (prefixes need at least 8 characters).");
-        }
-        if (resolution.target.id === this.client.sessionId) {
-            throw new Fault(400, "self_target", "Choose another peer.");
-        }
-        return resolution.target;
+        return resolveBridgeTarget(await this.peers(signal), to, this.client.sessionId);
     }
     async send(peer, message, context, options = {}) {
+        await this.connect(context.signal);
         const { signal, requestId } = context;
         context.onPeer(peer);
         this.guard(signal);
@@ -337,30 +345,19 @@ export class Session {
         }
     }
     ack(ids) {
-        const acked = [];
-        const retained = [];
-        for (const id of ids) {
-            const entry = this.inbox.get(id);
-            if (entry?.message.expectsReply === true) {
-                retained.push(id);
-            }
-            else if (entry) {
-                this.remove(id);
-                acked.push(id);
-            }
-        }
+        const result = this.inbox.ack(ids);
         this.presence();
-        return { acked, retained };
+        return result;
     }
     async answer(replyTo, message, context) {
         const entry = this.inbox.get(replyTo);
         if (entry?.message.expectsReply !== true) {
             throw new Fault(404, "unknown_ask", "replyTo must identify an unanswered inbound ask.");
         }
-        if (entry.replying) {
+        if (this.replying.has(replyTo)) {
             throw new Fault(409, "reply_in_progress", "This ask already has a reply in flight.");
         }
-        entry.replying = true;
+        this.replying.add(replyTo);
         const peer = entry.from.id;
         context.onPeer(peer);
         try {
@@ -369,16 +366,16 @@ export class Session {
                 throw new Fault(409, "peer_offline", "Original ask sender is disconnected.");
             }
             this.guard(context.signal);
-            if (this.inbox.get(replyTo) !== entry) {
+            if (!this.inbox.get(replyTo)) {
                 throw new Fault(409, "ask_retired", "Inbound ask is no longer replyable.");
             }
             const data = { ...(await this.send(peer, message, context, { replyTo })) };
-            this.remove(replyTo);
+            this.inbox.remove(replyTo);
             this.presence();
             return data;
         }
         finally {
-            entry.replying = false;
+            this.replying.delete(replyTo);
         }
     }
     async execute(operation, context) {
@@ -386,6 +383,19 @@ export class Session {
         if (operation.route === "POST /v1/ask") {
             return this.ask(operation, context);
         }
+        if (operation.route === "GET /v1/inbox" || operation.route === "POST /v1/ack") {
+            // Durable reads/acks remain available while the local broker is down.
+            if (!this.inbox.persistent) {
+                await this.connect(context.signal);
+            }
+            if (operation.route === "POST /v1/ack") {
+                return this.ack(operation.ids);
+            }
+            return {
+                ...this.inbox.page(operation.after, operation.limit),
+                ...this.inbox.status(this.owner.losses(this.identity.fingerprint256)),
+            };
+        }
         await this.connect(context.signal);
         switch (operation.route) {
             case "POST /v1/register":
@@ -394,21 +404,9 @@ export class Session {
                 const sessions = await this.peers(context.signal);
                 return {
                     sessionId: this.client.sessionId,
-                    sessions: sessions.map(({ topics: _topics, subscriptions: _subscriptions, ...entry }) => {
-                        return Object.assign(entry, { target: formatSessionTarget(entry, sessions) });
-                    }),
+                    sessions: bridgeSessionList(sessions),
                 };
             }
-            case "GET /v1/inbox": {
-                const lostMessages = this.owner.losses(this.identity.fingerprint256);
-                return {
-                    messages: [...this.inbox.values()].map(({ from, message }) => ({ from, message })),
-                    overflow: lostMessages > 0,
-                    lostMessages,
-                };
-            }
-            case "POST /v1/ack":
-                return this.ack(operation.ids);
             case "POST /v1/send":
                 return {
                     ...(await this.send((await this.target(operation.to, context.signal)).id, operation.message, context)),

package/dist/pi-intercom/bridge-target.js

@@ -0,0 +1,22 @@
+import { resolveSessionTarget, formatSessionTarget, nativePeerId } from "./session-targets.js";
+import { Fault } from "./bridge-protocol.js";
+export function bridgeSessionList(peers) {
+    return peers.map(({ topics: _topics, subscriptions: _subscriptions, ...entry }) => ({
+        ...entry,
+        target: formatSessionTarget(entry, peers),
+    }));
+}
+export function resolveBridgeTarget(peers, to, self) {
+    const exactNative = peers.find((peer) => peer.id === nativePeerId(to));
+    const resolution = resolveSessionTarget(peers, exactNative?.id ?? to);
+    if (resolution.status === "none") {
+        throw new Fault(404, "peer_offline", "Peer is not connected.");
+    }
+    if (resolution.status !== "found" || !resolution.target) {
+        throw new Fault(409, "ambiguous_target", "Use an unambiguous peer name or session ID (prefixes need at least 8 characters).");
+    }
+    if (resolution.target.id === self) {
+        throw new Fault(400, "self_target", "Choose another peer.");
+    }
+    return resolution.target;
+}

package/dist/pi-intercom/bridge-wake.js

@@ -0,0 +1,158 @@
+import { log } from "./bridge-protocol.js";
+import { Mailbox } from "./bridge-mailbox.js";
+const POLL_MS = 15000;
+const FALLBACK_AFTER_MS = 120000;
+const MAX_BACKOFF_MS = 300000;
+export class WakeDelivery {
+    controller = new AbortController();
+    timer;
+    running;
+    backoff = POLL_MS;
+    name;
+    mailbox;
+    policy;
+    authorized;
+    constructor(name, mailbox, policy, authorized) {
+        this.name = name;
+        this.mailbox = mailbox;
+        this.policy = policy;
+        this.authorized = authorized;
+    }
+    start() {
+        if (!this.running && !this.controller.signal.aborted) {
+            this.schedule(0);
+        }
+    }
+    schedule(delay) {
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.running = this.deliver()
+                .catch(() => {
+                log("wake_delivery", { name: this.name, result: "storage_unavailable" });
+                this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+            })
+                .finally(() => {
+                this.running = undefined;
+                if (!this.controller.signal.aborted) {
+                    this.schedule(this.backoff);
+                }
+            });
+        }, delay);
+    }
+    async deliver() {
+        if (!this.authorized()) {
+            return;
+        }
+        const entries = this.mailbox.pendingNotifications().messages;
+        for (const entry of entries) {
+            if (entry.acknowledged) {
+                // The box's durable worker owns primary wake/replay after acknowledgement.
+                this.mailbox.notificationAccepted(entry.message.id);
+            }
+        }
+        const next = entries.find((entry) => !entry.acknowledged && Date.now() - entry.receivedAt >= FALLBACK_AFTER_MS);
+        if (next) {
+            // One fallback wakes the box to drain the remaining mailbox; never flood a reset VM.
+            await this.post(next);
+            return;
+        }
+        this.backoff = POLL_MS;
+    }
+    async post(entry) {
+        if (!this.authorized()) {
+            return;
+        }
+        const fields = { name: this.name, messageId: entry.message.id };
+        try {
+            const response = await fetch(this.policy.url, {
+                method: "POST",
+                redirect: "error",
+                headers: {
+                    Authorization: `Bearer ${this.policy.key}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    from: entry.from.name ?? entry.from.id,
+                    from_id: entry.from.id,
+                    to: this.name,
+                    message_id: entry.message.id,
+                    ask_id: entry.message.expectsReply === true ? entry.message.id : null,
+                    text: entry.message.content.text,
+                }),
+                signal: AbortSignal.any([this.controller.signal, AbortSignal.timeout(10000)]),
+            });
+            await response.body?.cancel();
+            if (response.ok && !this.controller.signal.aborted && this.authorized()) {
+                // HTTP acceptance cannot prove durable intake; the same ID remains pending until inbox ACK.
+                this.backoff = MAX_BACKOFF_MS;
+                log("wake_delivery", { ...fields, result: "accepted" });
+            }
+            else {
+                this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+                log("wake_delivery", { ...fields, result: "http_rejected", status: response.status });
+            }
+        }
+        catch {
+            this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+            if (!this.controller.signal.aborted) {
+                log("wake_delivery", { ...fields, result: "transport_unconfirmed" });
+            }
+        }
+    }
+    async stop() {
+        this.controller.abort();
+        clearTimeout(this.timer);
+        await this.running;
+    }
+}
+export class WakeDeliveries {
+    stateDir;
+    allowed;
+    deliveries = new Map();
+    cleanup = new Set();
+    constructor(stateDir, allowed) {
+        this.stateDir = stateDir;
+        this.allowed = allowed;
+    }
+    session(identity, expires) {
+        if (!identity.wake ||
+            this.stateDir === undefined ||
+            this.deliveries.has(identity.fingerprint256)) {
+            return;
+        }
+        const mailbox = new Mailbox(this.stateDir, identity.fingerprint256, true);
+        const worker = new WakeDelivery(identity.name, mailbox, identity.wake, () => this.allowed(identity) && expires > Date.now());
+        this.deliveries.set(identity.fingerprint256, { identity, mailbox, worker });
+        worker.start();
+    }
+    drop(fp) {
+        const delivery = this.deliveries.get(fp);
+        if (!delivery) {
+            return;
+        }
+        this.deliveries.delete(fp);
+        const cleanup = delivery.worker
+            .stop()
+            .then(() => delivery.mailbox.close())
+            .catch(() => {
+            log("wake_delivery", { name: delivery.identity.name, result: "cleanup_failed" });
+        })
+            .finally(() => {
+            this.cleanup.delete(cleanup);
+        });
+        this.cleanup.add(cleanup);
+    }
+    reload() {
+        for (const [fp, delivery] of this.deliveries) {
+            if (!this.allowed(delivery.identity)) {
+                this.drop(fp);
+            }
+        }
+    }
+    async stop() {
+        for (const fp of this.deliveries.keys()) {
+            this.drop(fp);
+        }
+        await Promise.all(this.cleanup);
+    }
+}