@fitchmultz/pi-subagents 0.46.2 → 0.48.0

package/src/pi-intercom/bridge-session.ts

@@ -1,37 +1,31 @@
 import { randomUUID } from "node:crypto";
 import { IntercomClient } from "./broker/client.ts";
-import {
-  formatSessionTarget,
-  resolveSessionProjectId,
-  resolveSessionTarget,
-} from "./session-targets.ts";
+import { resolveSessionProjectId } from "./session-targets.ts";
 import type { Message, SendResult, SessionInfo } from "./types.ts";
 import type { Identity } from "./bridge-config.ts";
-import { Fault, INBOX_BYTES, INBOX_COUNT, cancelled, log, wait } from "./bridge-protocol.ts";
+import { Fault, cancelled, log, wait } from "./bridge-protocol.ts";
+import { Mailbox } from "./bridge-mailbox.ts";
 import type { UnknownRecord } from "../shared/unknown.ts";
 import type { MessagingOperation as Operation } from "./bridge-routes.ts";
+import type { RequestContext } from "./bridge-http.ts";
+import { resolveBridgeTarget, bridgeSessionList } from "./bridge-target.ts";
+import { ControlReplies } from "./bridge-control.ts";
+import type { NativeControlOperation } from "./native-control-protocol.ts";
 
-import { WaitingAsk, type Envelope } from "./bridge-ask.ts";
+import { WaitingAsk } from "./bridge-ask.ts";
 const MAX_REQUESTS = 8;
 const IDLE_TIMEOUT = 5 * 60 * 1000;
 const SEND_TIMEOUT = 8000;
 const LIST_TIMEOUT = 5000;
 
-interface InboxEntry extends Envelope {
-  readonly bytes: number;
-  replying: boolean;
-}
-interface RequestContext {
-  readonly signal: AbortSignal;
-  readonly requestId: string;
-  readonly onPeer: (peer: string) => void;
-}
 interface SendOptions {
   readonly messageId?: string;
   readonly replyTo?: string;
   readonly expectsReply?: boolean;
 }
 export interface SessionOwner {
+  readonly stateDir?: string;
+  readonly notifications?: boolean;
   readonly allowed: (identity: Identity) => boolean;
   readonly lost: (fp: string, count?: number) => void;
   readonly retired: (fp: string, generation: string) => void;
@@ -48,9 +42,10 @@ export class Session {
     listTimeoutMs: LIST_TIMEOUT,
   });
   private readonly requests = new Set<AbortController>();
-  private readonly inbox = new Map<string, InboxEntry>();
-  private inboxBytes = 0;
+  private readonly inbox: Mailbox;
+  private readonly replying = new Set<string>();
   private pending?: WaitingAsk;
+  private readonly controls = new ControlReplies();
   private closed = false;
   private connecting?: Promise<void>;
   private disconnecting?: Promise<void>;
@@ -62,6 +57,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.")),
     );
@@ -86,6 +82,9 @@ export class Session {
     if (this.closed) {
       throw this.closeReason;
     }
+    this.authorize();
+  }
+  authorize(): void {
     if (!this.owner.allowed(this.identity)) {
       throw new Fault(403, "revoked", "Identity is no longer authorized.");
     }
@@ -153,6 +152,7 @@ export class Session {
       this.close(fault);
       throw fault;
     }
+    this.presence();
     log("registered", this.fields());
   }
   private async connect(signal: AbortSignal): Promise<void> {
@@ -192,27 +192,23 @@ 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: Readonly<Fault>): void {
+  close(fault: Readonly<Fault>): void {
     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();
-  }
-  private startRetirement(): void {
     this.retirement = this.retire().catch((caught: unknown) => this.cleanupFailed(caught));
   }
   async settled(): Promise<void> {
@@ -220,17 +216,12 @@ export class Session {
   }
 
   private peerLeft(id: string): void {
+    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();
   }
   private receive(from: SessionInfo, message: Message): void {
@@ -247,50 +238,69 @@ export class Session {
       );
       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);
+  }
+  private storeReceive(from: SessionInfo, message: Message): void {
+    let result: "stored" | "duplicate" | "lost";
+    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();
   }
-  private remove(id: string): void {
-    const entry = this.inbox.get(id);
-    if (entry) {
-      this.inboxBytes -= entry.bytes;
-      this.inbox.delete(id);
+  private resolveReply(from: SessionInfo, message: Message): boolean {
+    const pending = this.pending;
+    if (pending?.matches(from.id, message.replyTo) !== true) {
+      return false;
     }
+    pending.resolve({ from, message });
+    return true;
+  }
+  private recordReceive(
+    peer: string,
+    messageId: string,
+    result: "stored" | "duplicate" | "lost",
+  ): void {
+    log(result === "lost" ? "inbox_overflow" : "received", {
+      ...this.fields(),
+      peer,
+      messageId,
+      result: result === "lost" && this.inbox.persistent ? "storage_failed" : result,
+    });
   }
   private presence(): void {
     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());
   }
   private async peers(signal: AbortSignal): Promise<SessionInfo[]> {
     this.guard(signal);
@@ -311,29 +321,29 @@ export class Session {
     await this.connect(signal);
     return this.peers(signal);
   }
+  async nativeControl(
+    operation: NativeControlOperation,
+    certificate: string,
+    context: RequestContext,
+  ): Promise<UnknownRecord> {
+    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) },
+    );
+  }
   private async target(to: string, signal: AbortSignal): Promise<SessionInfo> {
-    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);
   }
-  private async send(
+  async send(
     peer: string,
     message: string,
     context: RequestContext,
     options: SendOptions = {},
   ): Promise<SendResult> {
+    await this.connect(context.signal);
     const { signal, requestId } = context;
     context.onPeer(peer);
     this.guard(signal);
@@ -421,19 +431,9 @@ export class Session {
     }
   }
   private ack(ids: readonly string[]): UnknownRecord {
-    const acked: string[] = [];
-    const retained: string[] = [];
-    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;
   }
   private async answer(
     replyTo: string,
@@ -444,10 +444,10 @@ export class Session {
     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 {
@@ -456,15 +456,15 @@ 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: Operation, context: RequestContext): Promise<UnknownRecord> {
@@ -472,6 +472,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":
@@ -480,21 +493,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) });
-          }),
-        };
-      }
-      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,
+          sessions: bridgeSessionList(sessions),
         };
       }
-      case "POST /v1/ack":
-        return this.ack(operation.ids);
       case "POST /v1/send":
         return {
           ...(await this.send(

package/src/pi-intercom/bridge-target.ts

@@ -0,0 +1,35 @@
+import { resolveSessionTarget, formatSessionTarget, nativePeerId } from "./session-targets.ts";
+import { Fault } from "./bridge-protocol.ts";
+import type { SessionInfo } from "./types.ts";
+
+export function bridgeSessionList(
+  peers: readonly SessionInfo[],
+): readonly (SessionInfo & { readonly target: string })[] {
+  return peers.map(({ topics: _topics, subscriptions: _subscriptions, ...entry }) => ({
+    ...entry,
+    target: formatSessionTarget(entry, peers),
+  }));
+}
+
+export function resolveBridgeTarget(
+  peers: readonly SessionInfo[],
+  to: string,
+  self: string | null,
+): SessionInfo {
+  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/src/pi-intercom/bridge-wake.ts

@@ -0,0 +1,188 @@
+import { log } from "./bridge-protocol.ts";
+import { Mailbox, type PendingNotification } from "./bridge-mailbox.ts";
+import type { Identity, WakePolicy } from "./bridge-config.ts";
+
+const POLL_MS = 15000;
+const FALLBACK_AFTER_MS = 120000;
+const MAX_BACKOFF_MS = 300000;
+
+export class WakeDelivery {
+  private readonly controller = new AbortController();
+  private timer?: NodeJS.Timeout;
+  private running?: Promise<void>;
+  private backoff = POLL_MS;
+  private readonly name: string;
+  private readonly mailbox: Pick<Mailbox, "pendingNotifications" | "notificationAccepted">;
+  private readonly policy: WakePolicy;
+  private readonly authorized: () => boolean;
+
+  constructor(
+    name: string,
+    mailbox: Pick<Mailbox, "pendingNotifications" | "notificationAccepted">,
+    policy: WakePolicy,
+    authorized: () => boolean,
+  ) {
+    this.name = name;
+    this.mailbox = mailbox;
+    this.policy = policy;
+    this.authorized = authorized;
+  }
+
+  start(): void {
+    if (!this.running && !this.controller.signal.aborted) {
+      this.schedule(0);
+    }
+  }
+
+  private schedule(delay: number): void {
+    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);
+  }
+
+  private async deliver(): Promise<void> {
+    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;
+  }
+
+  private async post(entry: PendingNotification): Promise<void> {
+    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(): Promise<void> {
+    this.controller.abort();
+    clearTimeout(this.timer);
+    await this.running;
+  }
+}
+
+export class WakeDeliveries {
+  private readonly stateDir: string | undefined;
+  private readonly allowed: (identity: Identity) => boolean;
+  private readonly deliveries = new Map<
+    string,
+    { readonly identity: Identity; readonly mailbox: Mailbox; readonly worker: WakeDelivery }
+  >();
+  private readonly cleanup = new Set<Promise<unknown>>();
+
+  constructor(stateDir: string | undefined, allowed: (identity: Identity) => boolean) {
+    this.stateDir = stateDir;
+    this.allowed = allowed;
+  }
+
+  session(identity: Identity, expires: number): void {
+    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: string): void {
+    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(): void {
+    for (const [fp, delivery] of this.deliveries) {
+      if (!this.allowed(delivery.identity)) {
+        this.drop(fp);
+      }
+    }
+  }
+
+  async stop(): Promise<void> {
+    for (const fp of this.deliveries.keys()) {
+      this.drop(fp);
+    }
+    await Promise.all(this.cleanup);
+  }
+}