@fitchmultz/pi-subagents 0.52.4 → 0.52.5

package/src/pi-intercom/broker/broker.ts

@@ -116,9 +116,7 @@ class IntercomBroker {
     if (currentId === null && msg.type !== "register") {
       throw new Error(`Received ${msg.type} before register`);
     }
-    if (currentId !== null) {
-      this.touchActivity(currentId, false);
-    }
+    this.touchActivity(currentId, false);
     if (msg.type === "register") {
       if (currentId !== null) {
         throw new Error("Received duplicate register message");
@@ -152,7 +150,8 @@ class IntercomBroker {
         break;
       case "park":
       case "unpark":
-        this.parking.park(socket, currentId, msg.type === "park");
+      case "wake_result":
+        this.parking.handle(socket, currentId, msg);
         break;
       default:
         throw new Error(`Unknown client message type: ${msg.type}`);
@@ -172,7 +171,7 @@ class IntercomBroker {
       topics: resumed?.topics ?? new TopicSnapshot(info),
       topicFrames,
       lastMessages: msg.lastMessages === true,
-      parking: msg.parking === true,
+      ...this.parking.features(msg),
       receiptReads: msg.receiptReads === 1,
     });
     setId(id);
@@ -185,6 +184,7 @@ class IntercomBroker {
       sessionId: id,
       lastMessages: true,
       parking: msg.parking === true,
+      ...this.parking.capabilities(msg),
       receiptReads: 1,
       ...(msg.guardedDelivery === 1 ? { guardedDelivery: 1 } : {}),
       ...(topicFrames ? { topicsSupported: true, topicFrames: true } : {}),
@@ -397,13 +397,14 @@ class IntercomBroker {
       accepted: reason === null,
       delivered: reason === null && !queued,
       ...(queued ? { queued } : {}),
+      ...(queued ? { reason: this.parking.queueReason(target, message.id) } : {}),
       ...(reason !== null ? { reason } : {}),
     };
   }
 
   /** Update liveness/intercom-activity timestamps for a connected session. */
-  private touchActivity(sessionId: string, comms: boolean): void {
-    const session = this.sessions.get(sessionId);
+  private touchActivity(sessionId: string | null, comms: boolean): void {
+    const session = sessionId === null ? undefined : this.sessions.get(sessionId);
     if (!session) {
       return;
     }

package/src/pi-intercom/broker/client-wake.ts

@@ -0,0 +1,61 @@
+import type net from "node:net";
+import type { EventEmitter } from "node:events";
+import type { WakeResult } from "../types.ts";
+import type { UnknownRecord } from "../../shared/unknown.ts";
+import { validateIntercomMessageSize, writeMessage } from "./framing.ts";
+
+/** Negotiated wake outcomes; old brokers and clients keep the original wake event. */
+export class WakeMessages {
+  supported = false;
+  private readonly events: EventEmitter;
+  private readonly socket: () => net.Socket;
+  constructor(events: EventEmitter, socket: () => net.Socket) {
+    this.events = events;
+    this.socket = socket;
+  }
+  registration(): { wakeResults?: 1; wakeNotices?: 1 } {
+    return {
+      ...(this.events.listenerCount("wake_request") > 0 ? { wakeResults: 1 } : {}),
+      ...(this.events.listenerCount("wake_failed") > 0 ? { wakeNotices: 1 } : {}),
+    };
+  }
+  receive(msg: UnknownRecord): void {
+    if (msg.type === "wake_registered") {
+      if (typeof msg.requestId !== "string") {
+        throw new Error("Invalid wake registration");
+      }
+      this.events.emit("wake_registered", msg.requestId);
+      return;
+    }
+    if (typeof msg.sessionId !== "string") {
+      throw new Error("Invalid wake message");
+    }
+    if (msg.type === "wake") {
+      if (this.supported && typeof msg.requestId === "string") {
+        this.events.emit("wake_request", msg.sessionId, msg.requestId);
+      } else {
+        this.events.emit("wake", msg.sessionId);
+      }
+      return;
+    }
+    if (typeof msg.messageId !== "string" || typeof msg.reason !== "string") {
+      throw new Error("Invalid wake failure");
+    }
+    this.events.emit("wake_failed", msg.sessionId, msg.messageId, msg.reason);
+  }
+  respond(requestId: string, result: WakeResult): void {
+    if (!this.supported) {
+      return;
+    }
+    const frame = { type: "wake_result", requestId, result };
+    writeMessage(
+      this.socket(),
+      validateIntercomMessageSize(frame) === null
+        ? frame
+        : {
+            ...frame,
+            result: { status: "failed", reason: "Wake failed; inspect the agent run for details." },
+          },
+    );
+  }
+}

package/src/pi-intercom/broker/client.ts

@@ -6,6 +6,7 @@ import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
 import { LastMessageRequests, lastRequest } from "./client-last.ts";
 import { ParkRequests } from "./client-park.ts";
+import { WakeMessages } from "./client-wake.ts";
 import { isNativeReadResult } from "./last.ts";
 import {
   errorMessage,
@@ -66,6 +67,7 @@ export class IntercomClient extends EventEmitter {
   private _sessionId: string | null = null;
   private _topicsSupported = false;
   private readonly parking = new ParkRequests();
+  readonly wakes = new WakeMessages(this, () => this.requireActiveSocket());
   private guardedDeliverySupported = false;
   private readonly lastRequests: LastMessageRequests;
   private readonly pendingSends = new Map<
@@ -158,6 +160,7 @@ export class IntercomClient extends EventEmitter {
           this._topicsSupported = false;
           this.parking.settle(false);
           this.guardedDeliverySupported = false;
+          this.wakes.supported = false;
           this.disconnecting = false;
           this.failPending(error);
           if (established && !expected) {
@@ -177,6 +180,7 @@ export class IntercomClient extends EventEmitter {
           parking: true,
           receiptReads: 1,
           guardedDelivery: 1,
+          ...this.wakes.registration(),
         });
       } catch (error) {
         if (this.connection === connection) {
@@ -213,46 +217,47 @@ export class IntercomClient extends EventEmitter {
       throw new Error("Invalid broker message");
     }
 
-    const brokerMessage = msg;
-    const type = msg.type;
-
-    if (this._sessionId === null && type !== "registered") {
-      throw new Error(`Received ${type} before registered`);
+    if (this._sessionId === null && msg.type !== "registered") {
+      throw new Error(`Received ${msg.type} before registered`);
     }
 
-    switch (type) {
+    switch (msg.type) {
       case "registered":
-        this.receiveRegistration(brokerMessage);
+        this.receiveRegistration(msg);
         break;
       case "sessions":
-        this.receiveSessions(brokerMessage);
+        this.receiveSessions(msg);
         break;
       case "last_request":
-        this.receiveLastRequest(brokerMessage);
+        this.receiveLastRequest(msg);
         break;
       case "last_response":
-        this.lastRequests.receive(brokerMessage);
+        this.lastRequests.receive(msg);
         break;
       case "message":
-        this.receiveMessage(brokerMessage);
+        this.receiveMessage(msg);
         break;
       case "delivered":
       case "delivery_queued":
       case "delivery_failed":
-        this.receiveDelivery(brokerMessage);
+        this.receiveDelivery(msg);
         break;
       case "parked":
         this.parking.settle(true);
         break;
-      case "wake":
       case "session_left":
-        if (typeof brokerMessage.sessionId !== "string") {
-          throw new Error(`Invalid ${type} message`);
+        if (typeof msg.sessionId !== "string") {
+          throw new Error(`Invalid ${msg.type} message`);
         }
-        this.emit(type, brokerMessage.sessionId);
+        this.emit(msg.type, msg.sessionId);
+        break;
+      case "wake":
+      case "wake_failed":
+      case "wake_registered":
+        this.wakes.receive(msg);
         break;
       default:
-        throw new Error(`Unknown broker message type: ${type}`);
+        throw new Error(`Unknown broker message type: ${msg.type}`);
     }
   }
 
@@ -269,6 +274,7 @@ export class IntercomClient extends EventEmitter {
     this.parking.supported = msg.parking === true;
     this.lastRequests.receiptReads = msg.receiptReads === 1;
     this.guardedDeliverySupported = msg.guardedDelivery === 1;
+    this.wakes.supported = msg.wakeResults === 1;
     this.connection?.confirmRegistration();
     this.emit("_registered", { type: "registered", sessionId: msg.sessionId });
   }

package/src/pi-intercom/broker/parked.ts

@@ -2,19 +2,35 @@ import type net from "net";
 import { randomUUID } from "crypto";
 import type { Message, SessionInfo } from "../types.ts";
 import { nativePeerId } from "../session-targets.ts";
-import { writeMessage } from "./framing.ts";
+import { isRecord, type UnknownRecord } from "../../shared/unknown.ts";
+import type { WakeResult } from "../../shared/parking.ts";
+import { validateIntercomMessageSize, writeMessage } from "./framing.ts";
 
-type Retained = Array<{ readonly from: SessionInfo; readonly message: Message }>;
+type Retained = Array<{
+  readonly from: SessionInfo;
+  readonly sender: net.Socket | undefined;
+  readonly message: Message;
+}>;
+interface WakeAttempt {
+  readonly id: string;
+  readonly owner: net.Socket;
+  readonly count: number;
+  retry: boolean;
+}
 interface Parked {
   readonly retained: Retained;
   /** The fenced actor's socket closed: input waits for its restored replacement. */
   closed: boolean;
+  attempt?: WakeAttempt;
+  lastFailure?: string;
 }
 export interface ParkablePeer {
   readonly socket: net.Socket;
   readonly info: SessionInfo;
   /** This client can park itself, or wake and answer for its parked children. */
   readonly parking: boolean;
+  readonly wakeResults: boolean;
+  readonly wakeNotices: boolean;
   parked?: Parked;
 }
 export function reachable<T extends ParkablePeer>(target?: T): target is T {
@@ -25,6 +41,17 @@ type Deliver = (id: string, from: SessionInfo, message: Message) => string | nul
 function requested(id: unknown): string | undefined {
   return typeof id === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(id) ? id : undefined;
 }
+function wakeResponse(msg: UnknownRecord): { id: string; result: WakeResult } {
+  if (typeof msg.requestId === "string" && isRecord(msg.result)) {
+    if (msg.result.status === "requested") {
+      return { id: msg.requestId, result: { status: "requested" } };
+    }
+    if (msg.result.status === "failed" && typeof msg.result.reason === "string") {
+      return { id: msg.requestId, result: { status: "failed", reason: msg.result.reason } };
+    }
+  }
+  throw new Error("Invalid wake response");
+}
 
 /** A fenced child keeps its identity and queued input; it never departs while parked. */
 export class ParkedSessions<T extends ParkablePeer> {
@@ -34,7 +61,21 @@ export class ParkedSessions<T extends ParkablePeer> {
     this.sessions = sessions;
     this.deliver = deliver;
   }
-  park(socket: net.Socket, id: string, on: boolean): void {
+  handle(socket: net.Socket, id: string, msg: UnknownRecord): boolean {
+    if (msg.type === "park" || msg.type === "unpark") {
+      this.park(socket, id, msg.type === "park");
+      return true;
+    }
+    if (msg.type === "wake_result") {
+      const owner = this.sessions.get(id);
+      if (owner) {
+        this.respond(owner, msg);
+      }
+      return true;
+    }
+    return false;
+  }
+  private park(socket: net.Socket, id: string, on: boolean): void {
     const session = this.sessions.get(id);
     if (on && session?.parking === true) {
       session.parked ??= { retained: [], closed: false };
@@ -75,6 +116,7 @@ export class ParkedSessions<T extends ParkablePeer> {
   }
   /** Flushes a restored child's input and re-sends wakes owed to a (re)registered main. */
   registered(id: string, previous?: T): void {
+    this.registeredWake(previous);
     this.flush(id, previous?.parked?.retained ?? []);
     for (const child of this.sessions.values()) {
       if (nativePeerId(child.info.rootSessionId ?? "") === id) {
@@ -82,6 +124,26 @@ export class ParkedSessions<T extends ParkablePeer> {
       }
     }
   }
+  private registeredWake(previous?: T): void {
+    const main = previous && this.main(previous);
+    const attempt = previous?.parked?.attempt;
+    if (reachable(main) && attempt?.owner === main.socket) {
+      writeMessage(main.socket, { type: "wake_registered", requestId: attempt.id });
+    }
+  }
+  capabilities(msg: UnknownRecord): { wakeResults?: 1; wakeNotices?: 1 } {
+    return {
+      ...(msg.wakeResults === 1 ? { wakeResults: 1 } : {}),
+      ...(msg.wakeNotices === 1 ? { wakeNotices: 1 } : {}),
+    };
+  }
+  features(msg: UnknownRecord): Pick<ParkablePeer, "parking" | "wakeResults" | "wakeNotices"> {
+    return {
+      parking: msg.parking === true,
+      wakeResults: msg.wakeResults === 1,
+      wakeNotices: msg.wakeNotices === 1,
+    };
+  }
   /** A transport handoff, not a departure: no session_left and queued input stays. */
   closed(session: T): boolean {
     const { parked } = session;
@@ -101,12 +163,22 @@ export class ParkedSessions<T extends ParkablePeer> {
     );
   }
   retain(target: T | undefined, from: SessionInfo, message: Message): boolean {
-    target?.parked?.retained.push({ from, message });
-    if (target) {
+    target?.parked?.retained.push({ from, message, sender: this.sessions.get(from.id)?.socket });
+    if (target && this.waking(message)) {
       this.wake(target);
     }
     return target?.parked !== undefined;
   }
+  queueReason(target: T | undefined, messageId: string): string {
+    const last = target?.parked?.lastFailure;
+    const reason =
+      last === undefined
+        ? "Queued for a parked child; delivery awaits its return."
+        : `Queued for a parked child; the last wake failed: ${last} The message may still arrive after a later wake.`;
+    return validateIntercomMessageSize({ type: "delivery_queued", messageId, reason }) === null
+      ? reason
+      : "Queued for a parked child; its last wake failed. Inspect the agent run for details.";
+  }
   /** Reads of an exited parked child go to its main, which answers from captured history. */
   reader(id: string): T | undefined {
     const child = this.sessions.get(id);
@@ -115,14 +187,84 @@ export class ParkedSessions<T extends ParkablePeer> {
   // Passive breadcrumbs and topic updates wait for a genuine wake; they never spawn the child.
   private wake(child: T): void {
     const main = this.main(child);
-    const wakes = child.parked?.retained.some(
-      ({ message }) =>
-        message.passive !== true && message.delivery !== "passive" && message.topic === undefined,
-    );
-    if (main && child.parked?.closed === true && wakes === true) {
+    const parked = child.parked;
+    if (
+      !reachable(main) ||
+      parked?.closed !== true ||
+      !parked.retained.some(({ message }) => this.waking(message))
+    ) {
+      return;
+    }
+    if (!main.wakeResults) {
       writeMessage(main.socket, { type: "wake", sessionId: child.info.id });
+      return;
+    }
+    if (parked.attempt?.owner === main.socket) {
+      parked.attempt.retry = true;
+      return;
+    }
+    const attempt = {
+      id: randomUUID(),
+      owner: main.socket,
+      count: parked.retained.length,
+      retry: false,
+    };
+    parked.attempt = attempt;
+    writeMessage(main.socket, { type: "wake", sessionId: child.info.id, requestId: attempt.id });
+  }
+  private waking(message: Message): boolean {
+    return (
+      message.passive !== true && message.delivery !== "passive" && message.topic === undefined
+    );
+  }
+  /** Only the main sent this request can report it, and only while that child stays parked. */
+  private respond(owner: T, msg: UnknownRecord): void {
+    const { id, result } = wakeResponse(msg);
+    const child = [...this.sessions.values()].find(
+      (peer) =>
+        peer.parked?.attempt?.id === id &&
+        peer.parked.attempt.owner === owner.socket &&
+        this.main(peer) === owner,
+    );
+    const parked = child?.parked;
+    const attempt = parked?.attempt;
+    if (!child || !parked || !attempt) {
+      return;
+    }
+    parked.attempt = undefined;
+    if (result.status === "failed") {
+      parked.lastFailure = result.reason;
+      for (const retained of parked.retained.slice(0, attempt.count)) {
+        this.notify(child, retained, result.reason);
+      }
+    }
+    if (attempt.retry) {
+      this.wake(child);
     }
   }
+  private notify(child: T, { from, sender, message }: Retained[number], reason: string): void {
+    const origin = this.sessions.get(from.id);
+    if (
+      message.expectsReply !== true ||
+      origin?.wakeNotices !== true ||
+      origin.socket !== sender ||
+      !reachable(origin)
+    ) {
+      return;
+    }
+    const frame = {
+      type: "wake_failed",
+      sessionId: child.info.id,
+      messageId: message.id,
+      reason,
+    };
+    writeMessage(
+      origin.socket,
+      validateIntercomMessageSize(frame) === null
+        ? frame
+        : { ...frame, reason: "Wake failed; inspect the agent run for details." },
+    );
+  }
   private main(child: T): T | undefined {
     const main = this.sessions.get(nativePeerId(child.info.rootSessionId ?? ""));
     return main?.parking === true && main.parked === undefined ? main : undefined;

package/src/pi-intercom/broker/spawn.ts

@@ -72,9 +72,14 @@ function toError(error: unknown): Error {
 export async function spawnBrokerIfNeeded(
   brokerCommand: string,
   brokerArgs: readonly string[],
+  warning: (message?: string) => void = (message) => {
+    if (message !== undefined) {
+      console.warn(message);
+    }
+  },
 ): Promise<void> {
   prepareBrokerSocketPath();
-  await warnPreviousBroker();
+  warning(await previousBrokerWarning());
 
   if (await isBrokerRunning()) {
     return;
@@ -170,24 +175,20 @@ function readLivePid(pidPath: string): number | null {
   return isBrokerPidReused(pid, raw) ? null : pid;
 }
 
-async function warnPreviousBroker(): Promise<void> {
+async function previousBrokerWarning(): Promise<string | undefined> {
   const previousSockets = getPreviousBrokerSocketPaths();
   for (const socketPath of previousSockets) {
     // Migration probes are sequential and never register or send to old peers.
     // oxlint-disable-next-line no-await-in-loop
     if (isOwnedBrokerSocket(socketPath) && (await checkOneSocket(socketPath))) {
-      console.warn(
-        "An older agent-directory Intercom broker is still running. Its peers are not part of shared same-user discovery until they reload with the updated extension. Existing sessions and accepted work are untouched; no legacy fallback is used.",
-      );
-      return;
+      return "An older agent-directory Intercom broker is still running. Its peers are not part of shared same-user discovery until they reload with the updated extension. Existing sessions and accepted work are untouched; no legacy fallback is used.";
     }
   }
   const previousPid = readLivePid(join(getPiAgentDir(), "intercom", "broker.pid"));
   if (previousPid !== null) {
-    console.warn(
-      `Older Intercom broker PID ${previousPid} may still own accepted work. Its peers need to reload with the updated extension to join shared same-user discovery. Nothing was stopped or replaced; no legacy fallback is used.`,
-    );
+    return `Older Intercom broker PID ${previousPid} may still own accepted work. Its peers need to reload with the updated extension to join shared same-user discovery. Nothing was stopped or replaced; no legacy fallback is used.`;
   }
+  return undefined;
 }
 
 export async function stopUnhealthyBrokerBeforeSpawn(): Promise<void> {

package/src/pi-intercom/config.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getPiAgentDir } from "./agent-dir.ts";
 import { isRecord, isUnknownArray } from "./validation.ts";
+import { errorMessage } from "../shared/unknown.ts";
 
 export interface IntercomConfig {
   /** Broker command used to spawn the broker process (for example, Node or Bun). */
@@ -93,7 +94,7 @@ function configuredTimeout(
   }
   return value;
 }
-export function loadConfig(): IntercomConfig {
+export function loadConfig(report: (message: string) => void = console.error): IntercomConfig {
   const configPath = join(getPiAgentDir(), "intercom", "config.json");
   if (!existsSync(configPath)) {
     return { ...defaults };
@@ -114,7 +115,9 @@ export function loadConfig(): IntercomConfig {
       listTimeoutMs: configuredTimeout(parsed, "listTimeoutMs"),
     };
   } catch (error) {
-    console.error(`Failed to load intercom config at ${configPath}:`, error);
+    report(
+      `Failed to load intercom config at ${configPath}: ${errorMessage(error)}. Using defaults.`,
+    );
     return { ...defaults };
   }
 }