@fitchmultz/pi-subagents 0.52.3 → 0.52.5

package/src/pi-intercom/connection.ts

@@ -10,6 +10,8 @@ import { readLastMessage, type NativeHistory } from "./last-message.ts";
 import { asError } from "./validation.ts";
 import { RecoveryError } from "./tool-results.ts";
 import { formatTargetOptions, resolveSessionTarget, nativePeerId } from "./session-targets.ts";
+import type { WakeResult } from "../shared/parking.ts";
+import type { BackgroundReporter } from "../shared/background-reporting.ts";
 
 type Lifecycle = Pick<
   Readonly<IntercomLifecycle>,
@@ -26,7 +28,8 @@ interface ConnectionHooks {
   readonly disconnected: (error: Readonly<Error>) => void;
   /** A main answers for and wakes its exited parked children. */
   readonly parkedHistory: (peer: SessionInfo) => Promise<NativeHistory | undefined>;
-  readonly wake: (peer: string) => void;
+  readonly wake: (peer: string, signal?: AbortSignal) => Promise<WakeResult>;
+  readonly wakeFailed: (peer: string, messageId: string, reason: string) => void;
 }
 interface LastRequest {
   readonly requestId: string;
@@ -46,10 +49,18 @@ export class IntercomConnection {
   private readonly lifecycle: Lifecycle;
   private readonly config: IntercomConfig;
   private readonly hooks: ConnectionHooks;
-  constructor(lifecycle: Lifecycle, config: IntercomConfig, hooks: ConnectionHooks) {
+  private readonly wakes = new Map<string, AbortController>();
+  private readonly reporter: BackgroundReporter;
+  constructor(
+    lifecycle: Lifecycle,
+    config: IntercomConfig,
+    hooks: ConnectionHooks,
+    reporter: BackgroundReporter,
+  ) {
     this.lifecycle = lifecycle;
     this.config = config;
     this.hooks = hooks;
+    this.reporter = reporter;
   }
   get active(): IntercomTransport | null {
     return this.client;
@@ -197,6 +208,22 @@ export class IntercomConnection {
       next.respondLast(request.requestId, { error: asError(error).message });
     }
   }
+  private receive(next: IntercomClient, from: SessionInfo, message: Message): void {
+    const ctx = this.lifecycle.live();
+    if (this.client !== next || !ctx) {
+      return;
+    }
+    const owner = `inbound:${from.id}:${message.id}`;
+    this.hooks
+      .incoming(ctx, from, message)
+      .then(() => this.reporter.recover(owner))
+      .catch((error: unknown) =>
+        this.reporter.report(
+          owner,
+          `Intercom inbound ${message.id} from ${from.id} failed: ${asError(error).message}`,
+        ),
+      );
+  }
   private createClient(): IntercomClient {
     const next = new IntercomClient({
       sendTimeoutMs: this.config.sendTimeoutMs,
@@ -207,17 +234,48 @@ export class IntercomConnection {
       this.answerLast(next, request);
     });
     next.on("message", (from: SessionInfo, message: Message) => {
-      const ctx = this.lifecycle.live();
-      if (this.client !== next || !ctx) {
-        return;
-      }
-      this.hooks.incoming(ctx, from, message).catch((error: unknown) => {
-        console.error("Intercom inbound delivery failed:", error);
-      });
+      this.receive(next, from, message);
     });
     next.on("wake", (peer: string) => {
       if (this.client === next) {
-        this.hooks.wake(peer);
+        void this.hooks.wake(peer).catch(() => {
+          // Old brokers cannot receive wake outcomes.
+        });
+      }
+    });
+    next.on("wake_request", (peer: string, requestId: string) => {
+      if (this.client === next) {
+        const registered = new AbortController();
+        this.wakes.set(requestId, registered);
+        void this.hooks
+          .wake(peer, registered.signal)
+          .catch((error: unknown): WakeResult => ({
+            status: "failed",
+            reason: asError(error).message,
+          }))
+          .then((result) => {
+            if (this.client === next && !registered.signal.aborted) {
+              next.wakes.respond(requestId, result);
+            }
+          })
+          .finally(() => {
+            if (this.wakes.get(requestId) === registered) {
+              this.wakes.delete(requestId);
+            }
+          })
+          .catch(() => {
+            // A lost broker transport retains the input for the next registration.
+          });
+      }
+    });
+    next.on("wake_registered", (requestId: string) => {
+      if (this.client === next) {
+        this.wakes.get(requestId)?.abort();
+      }
+    });
+    next.on("wake_failed", (peer: string, messageId: string, reason: string) => {
+      if (this.client === next) {
+        this.hooks.wakeFailed(peer, messageId, reason);
       }
     });
     next.on("session_left", (id: string) => {
@@ -231,6 +289,7 @@ export class IntercomConnection {
         return;
       }
       this.hooks.disconnected(error);
+      this.cancelWakes();
       this.client = null;
       this.lifecycle.transport(null);
       this.clearReconnect();
@@ -248,7 +307,13 @@ export class IntercomConnection {
   ): Promise<IntercomTransport> {
     const next = this.createClient();
     try {
-      await spawnBrokerIfNeeded(this.config.brokerCommand, this.config.brokerArgs);
+      await spawnBrokerIfNeeded(this.config.brokerCommand, this.config.brokerArgs, (message) => {
+        if (message === undefined) {
+          this.reporter.recover("older-broker");
+        } else {
+          this.reporter.report("older-broker", message, "warning");
+        }
+      });
       await next.connect(
         await this.lifecycle.registration(this.hooks.pendingAsks()),
         nativePeerId(sessionId),
@@ -261,6 +326,7 @@ export class IntercomConnection {
       this.lifecycle.transport(next.sessionId, next.supportsGuardedDelivery);
       this.syncIdentity(ctx.sessionManager.getSessionId());
       this.attempt = 0;
+      this.reporter.recover("connection-cleanup");
       return next;
     } catch (error) {
       if (this.client === next) {
@@ -268,7 +334,10 @@ export class IntercomConnection {
       }
       // A failed registration still owns its socket.
       await next.disconnect().catch((cleanupError: unknown) => {
-        console.error("Intercom failed connection cleanup:", cleanupError);
+        this.reporter.report(
+          "connection-cleanup",
+          `Intercom failed connection cleanup: ${asError(cleanupError).message}`,
+        );
       });
       throw asError(error);
     }
@@ -323,6 +392,7 @@ export class IntercomConnection {
   }
   async shutdown(): Promise<void> {
     this.clearTimers();
+    this.cancelWakes();
     // The bounded launcher attempt is joined before socket shutdown.
     await Promise.allSettled([this.connecting]);
     if (this.client) {
@@ -330,6 +400,12 @@ export class IntercomConnection {
       this.client = null;
     }
   }
+  private cancelWakes(): void {
+    for (const wake of this.wakes.values()) {
+      wake.abort();
+    }
+    this.wakes.clear();
+  }
 }
 export async function resolveConnectedTarget(
   active: IntercomTransport,

package/src/pi-intercom/inbound-delivery.ts

@@ -9,6 +9,8 @@ import type {
 } from "./runtime-types.ts";
 import { requestedDelivery } from "./inbound-record.ts";
 import { runCooperatively } from "../shared/cooperative.ts";
+import { asError } from "./validation.ts";
+import type { BackgroundReporter } from "../shared/background-reporting.ts";
 
 type Lifecycle = Pick<Readonly<IntercomLifecycle>, "generation" | "isIdle" | "live" | "toolCount">;
 type Journal = Readonly<
@@ -33,6 +35,7 @@ type Replies = Readonly<Pick<ReplyTracker, "queueTurnContext" | "reset">>;
 interface DeliveryHooks {
   readonly replies: Replies;
   readonly syncStatus: () => void;
+  readonly reporter: BackgroundReporter;
 }
 /** Owns cooperative inbound batches, restoration and the flush timer. */
 export class InboundDeliveryOwner {
@@ -108,9 +111,12 @@ export class InboundDeliveryOwner {
     this.clearTimer();
     this.timer = setTimeout(() => {
       this.timer = null;
-      this.flush(generation)?.catch((error: unknown) => {
-        console.error("Intercom inbound delivery failed:", error);
-      });
+      this.flush(generation)?.catch((error: unknown) =>
+        this.hooks.reporter.report(
+          "inbound-delivery",
+          `Intercom inbound delivery failed: ${asError(error).message}`,
+        ),
+      );
     }, delayMs);
     this.timer.unref();
   }
@@ -145,10 +151,19 @@ export class InboundDeliveryOwner {
       ) {
         this.schedule(0);
       }
+      this.hooks.reporter.recover("inbound-cleanup");
     };
-    task.then(finish, finish).catch((error: unknown) => {
-      console.error("Intercom inbound cleanup failed:", error);
-    });
+    task
+      .then(() => {
+        this.hooks.reporter.recover("inbound-delivery");
+        finish();
+      }, finish)
+      .catch((error: unknown) => {
+        this.hooks.reporter.report(
+          "inbound-cleanup",
+          `Intercom inbound cleanup failed: ${asError(error).message}`,
+        );
+      });
     return task;
   }
   private triggerIndex(entries: readonly PendingInboundMessage[]): number {

package/src/pi-intercom/index.ts

@@ -13,8 +13,9 @@ import { IntercomInspection } from "./inspection.ts";
 import { IntercomTools } from "./tools.ts";
 import { IntercomSessionEvents } from "./session-events.ts";
 import { registerIntercomTools } from "./tool-registration.ts";
-import { isParkRequest, PARK, PARKED_HISTORY, WAKE } from "../shared/parking.ts";
+import { isParkRequest, PARK, PARKED_HISTORY, WAKE, type WakeResult } from "../shared/parking.ts";
 import type { NativeHistory } from "./last-message.ts";
+import { BackgroundReporter } from "../shared/background-reporting.ts";
 
 /** The agent runtime answers for its exited parked child from the captured native session. */
 function parkedHistory(pi: ExtensionAPI, peer: string): Promise<NativeHistory | undefined> {
@@ -28,34 +29,76 @@ function parkedHistory(pi: ExtensionAPI, peer: string): Promise<NativeHistory |
   return history ?? Promise.reject(new Error("No agent runtime owns parked history."));
 }
 
-export default function piIntercomExtension(pi: ExtensionAPI): void {
-  const config = loadConfig();
+function wakeParked(pi: ExtensionAPI, peer: string, signal?: AbortSignal): Promise<WakeResult> {
+  let result: Promise<WakeResult> | undefined;
+  pi.events.emit(WAKE, {
+    peer,
+    signal,
+    reply: (outcome: Promise<WakeResult>) => {
+      result = outcome;
+    },
+  });
+  return (
+    result ??
+    Promise.resolve({ status: "failed", reason: "No agent runtime owns this parked child." })
+  );
+}
+
+function setupReporting(pi: ExtensionAPI) {
+  let configError: string | undefined;
+  const config = loadConfig((message) => {
+    configError = message;
+  });
   const lifecycle = new IntercomLifecycle(pi, config, readIntercomLineage());
+  const reporter = new BackgroundReporter(() => lifecycle.live());
+  let pendingConfigError = configError;
+  pi.on("session_start", (_event, ctx) => {
+    reporter.start();
+    if (pendingConfigError !== undefined) {
+      if (ctx.hasUI) {
+        ctx.ui.notify(pendingConfigError, "warning");
+      } else {
+        console.error(pendingConfigError);
+      }
+      pendingConfigError = undefined;
+    }
+  });
+  pi.on("session_shutdown", () => reporter.shutdown());
+  return { config, lifecycle, reporter };
+}
+
+export default function piIntercomExtension(pi: ExtensionAPI): void {
+  const { config, lifecycle, reporter } = setupReporting(pi);
   const replies = new ReplyTracker(config.askTimeoutMs);
   const journal = new InboundJournal(pi, lifecycle, replies);
   const wait = new ReplyWait(lifecycle, config.askTimeoutMs);
-  const connection = new IntercomConnection(lifecycle, config, {
-    restoring: () => delivery.restoring,
-    pendingAsks: () => replies.listPending().length,
-    receipt: (query) => journal.receipt(query),
-    incoming: (ctx, from, message) => inbound.receive(ctx, from, message),
-    peerLeft: (id) => {
-      wait.peerDisconnected(id);
-      journal.peerLeft(id);
-    },
-    disconnected: (error) => {
-      wait.reject(
-        new Error(`Disconnected while waiting for reply: ${error.message}`, { cause: error }),
-      );
-    },
-    parkedHistory: (peer) => parkedHistory(pi, peer.id),
-    wake: (peer) => {
-      pi.events.emit(WAKE, peer);
+  const connection = new IntercomConnection(
+    lifecycle,
+    config,
+    {
+      restoring: () => delivery.restoring,
+      pendingAsks: () => replies.listPending().length,
+      receipt: (query) => journal.receipt(query),
+      incoming: (ctx, from, message) => inbound.receive(ctx, from, message),
+      peerLeft: (id) => {
+        wait.peerDisconnected(id);
+        journal.peerLeft(id);
+      },
+      disconnected: (error) => {
+        wait.reject(
+          new Error(`Disconnected while waiting for reply: ${error.message}`, { cause: error }),
+        );
+      },
+      parkedHistory: (peer) => parkedHistory(pi, peer.id),
+      wake: (peer, signal) => wakeParked(pi, peer, signal),
+      wakeFailed: (peer, messageId, reason) => wait.wakeFailed(peer, messageId, reason),
     },
-  });
+    reporter,
+  );
   const delivery = new InboundDeliveryOwner(pi, lifecycle, journal, {
     replies,
     syncStatus: () => connection.syncStatus(),
+    reporter,
   });
   lifecycle.registerContextEvents(() => connection.syncStatus());
   const inbound = new IntercomInbound(lifecycle, config, {

package/src/pi-intercom/outbound.ts

@@ -23,6 +23,7 @@ import {
   AskDeliveryError,
   failureDetails,
   RecoveryError,
+  WakeFailedError,
   type RecoveryAction,
 } from "./tool-results.ts";
 import { sendOptions, toolError, toolText } from "./tool-arguments.ts";
@@ -220,6 +221,18 @@ export class IntercomOutbound {
     );
   }
   private askFailure(error: unknown, to: string, questionId: string | undefined): ToolResultLike {
+    if (error instanceof WakeFailedError) {
+      return toolError(
+        `The parked child could not be woken: ${error.message} Your ask is still queued and may arrive after a later wake. Check the recipient before sending it again.`,
+        failureDetails("wake_failed", [{ action: "list" }, { action: "status" }], {
+          error: true,
+          messageId: questionId,
+          accepted: true,
+          delivered: false,
+          queued: true,
+        }),
+      );
+    }
     if (error instanceof AskDeliveryError) {
       const result = this.deliveryFailure(to, error.result);
       return { ...result, details: { ...result.details, error: true } };
@@ -390,16 +403,27 @@ export class IntercomOutbound {
       this.owners.replies.markReplied(target.message.id);
       this.markActivity();
       this.recordSent(sender, { text: body, replyTo: target.message.id }, result);
-      return toolText(`Reply sent to ${sender}`, {
-        messageId: result.id,
-        delivered: true,
-        replyTo: target.message.id,
-        reasonCode: "reply_sent",
-      });
+      return this.replySent(sender, target.message.id, result);
     } catch (error) {
       return this.replyFailure(error, replyTo);
     }
   }
+  private replySent(sender: string, replyTo: string, result: SendResult): ToolResultLike {
+    const queued = result.queued === true;
+    return toolText(
+      queued
+        ? `Reply queued for ${sender} (${result.reason ?? "queued"})`
+        : `Reply sent to ${sender}`,
+      {
+        messageId: result.id,
+        accepted: result.accepted,
+        delivered: result.delivered,
+        queued,
+        replyTo,
+        reasonCode: queued ? "message_queued" : "reply_sent",
+      },
+    );
+  }
   private replyFailure(error: unknown, replyTo: string | undefined): ToolResultLike {
     const reason = error instanceof RecoveryError ? error.code : "reply_failed";
     const actions: readonly RecoveryAction[] =

package/src/pi-intercom/reply-wait.ts

@@ -3,7 +3,7 @@ import type { IntercomClient, SendResult } from "./broker/client.ts";
 import type { IntercomTransport } from "./transport.ts";
 import type { IntercomLifecycle } from "./lifecycle.ts";
 import { asError } from "./validation.ts";
-import { AskDeliveryError, RecoveryError } from "./tool-results.ts";
+import { AskDeliveryError, RecoveryError, WakeFailedError } from "./tool-results.ts";
 
 type Lifecycle = Readonly<Pick<IntercomLifecycle, "markActivity">>;
 interface ReplyWaiter {
@@ -47,6 +47,11 @@ export class ReplyWait {
       this.reject(new Error(`Reply peer disconnected before answering: ${id}`));
     }
   }
+  wakeFailed(peer: string, messageId: string, reason: string): void {
+    if (this.waiter?.from === peer && this.waiter.replyTo === messageId) {
+      this.reject(new WakeFailedError(reason));
+    }
+  }
   receive(
     sender: { readonly id: string; readonly name?: string },
     message: Message,

package/src/pi-intercom/tool-results.ts

@@ -46,6 +46,7 @@ export class AskDeliveryError extends Error {
     this.result = result;
   }
 }
+export class WakeFailedError extends Error {}
 export function throwIfToolError(result: ToolResultLike): ToolResultLike {
   if (result.isError !== true) {
     return result;

package/src/pi-intercom/types.ts

@@ -10,6 +10,10 @@ import {
   safeText,
 } from "./validation.ts";
 
+export type WakeResult =
+  | { readonly status: "requested" }
+  | { readonly status: "failed"; readonly reason: string };
+
 export interface SessionInfo {
   readonly id: string;
   readonly name?: string;

package/src/shared/background-reporting.ts

@@ -0,0 +1,78 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getPiAgentDir } from "../pi-intercom/agent-dir.ts";
+
+/** One active failure per owner. Recovery is established by the owner, not by the reporter. */
+export class BackgroundReporter {
+  private readonly episodes = new Map<string, string>();
+  private readonly context: () => ExtensionContext | null | undefined;
+  private shuttingDown = false;
+  private headless = false;
+  constructor(context: () => ExtensionContext | null | undefined) {
+    this.context = context;
+  }
+  start(): void {
+    this.shuttingDown = false;
+  }
+  shutdown(): void {
+    try {
+      this.headless = this.context()?.hasUI === false;
+    } catch {
+      this.headless = false;
+    }
+    this.shuttingDown = true;
+  }
+  recover(owner: string): void {
+    this.episodes.delete(owner);
+  }
+  private published(owner: string | undefined, message: string): void {
+    if (owner !== undefined) {
+      this.episodes.set(owner, message);
+    }
+  }
+  private repeated(owner: string | undefined, message: string): boolean {
+    return owner !== undefined && this.episodes.get(owner) === message;
+  }
+  report(
+    owner: string | undefined,
+    message: string,
+    severity: "warning" | "error" = "error",
+  ): void {
+    if (this.repeated(owner, message)) {
+      return;
+    }
+    if (this.shuttingDown && this.headless) {
+      console.error(message);
+      this.published(owner, message);
+      return;
+    }
+    try {
+      const ctx = this.context();
+      if (!this.shuttingDown && ctx) {
+        if (ctx.hasUI) {
+          ctx.ui.notify(message, severity);
+        } else {
+          console.error(message);
+        }
+        this.published(owner, message);
+        return;
+      }
+    } catch {
+      // A context may be invalidated between its owner's check and notification.
+    }
+    // Pi may have already stopped its renderer during session_shutdown. Never write to the terminal.
+    try {
+      const dir = path.join(getPiAgentDir(), "intercom");
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      fs.appendFileSync(
+        path.join(dir, "background-errors.log"),
+        `${new Date().toISOString()} ${message}\n`,
+        { mode: 0o600 },
+      );
+      this.published(owner, message);
+    } catch {
+      // No terminal write is safe here; the diagnostic store itself may be unavailable.
+    }
+  }
+}

package/src/shared/parking.ts

@@ -1,6 +1,9 @@
 import type { NativeHistory } from "../pi-intercom/last-message.ts";
+import type { WakeResult } from "../pi-intercom/types.ts";
 import { isRecord } from "./unknown.ts";
 
+export type { WakeResult } from "../pi-intercom/types.ts";
+
 /** A child actor asks its intercom to fence broker input before parking, or to release it. */
 export const PARK = "pi-subagents:park";
 export interface ParkRequest {
@@ -10,6 +13,11 @@ export interface ParkRequest {
 /** A main intercom wakes or reads an exited parked child through the agent runtime. */
 export const WAKE = "pi-subagents:wake";
 export const PARKED_HISTORY = "pi-subagents:parked-history";
+export interface WakeRequest {
+  readonly peer: string;
+  readonly signal?: AbortSignal;
+  readonly reply: (result: Promise<WakeResult>) => void;
+}
 export interface HistoryRequest {
   readonly peer: string;
   readonly reply: (history: Promise<NativeHistory | undefined>) => void;
@@ -17,6 +25,14 @@ export interface HistoryRequest {
 export function isParkRequest(value: unknown): value is ParkRequest {
   return isRecord(value) && typeof value.park === "boolean" && typeof value.reply === "function";
 }
+export function isWakeRequest(value: unknown): value is WakeRequest {
+  return (
+    isRecord(value) &&
+    typeof value.peer === "string" &&
+    typeof value.reply === "function" &&
+    (value.signal === undefined || value.signal instanceof AbortSignal)
+  );
+}
 export function isHistoryRequest(value: unknown): value is HistoryRequest {
   return isRecord(value) && typeof value.peer === "string" && typeof value.reply === "function";
 }