@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/src/pi-intercom/inbound.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { IntercomConfig } from "./config.ts";
 import type { IntercomLifecycle } from "./lifecycle.ts";
 import type { InboundDeliveryOwner } from "./inbound-delivery.ts";
+import type { InboundJournal } from "./inbound-journal.ts";
 import type { ReplyTracker } from "./reply-tracker.ts";
 import type { ReplyWait } from "./reply-wait.ts";
 import type { IntercomConnection } from "./connection.ts";
@@ -11,17 +12,18 @@ import { requestedDelivery } from "./inbound-record.ts";
 import { formatAttachments } from "./message-format.ts";
 
 type Lifecycle = Readonly<
-  Pick<IntercomLifecycle, "generation" | "isIdle" | "live" | "markActivity">
+  Pick<IntercomLifecycle, "accepts" | "generation" | "isIdle" | "live" | "markActivity">
 >;
 type InboundDeliveryHandle = Readonly<
-  Pick<InboundDeliveryOwner, "batching" | "detach" | "queue" | "restoring" | "send">
+  Pick<InboundDeliveryOwner, "batching" | "queue" | "restoring" | "send">
 >;
 type ReplyWaitHandle = Readonly<Pick<ReplyWait, "receive">>;
-type Connection = Readonly<Pick<IntercomConnection, "active" | "syncStatus">>;
-type Replies = Readonly<Pick<ReplyTracker, "markReplied" | "recordIncomingMessage">>;
+type Connection = Readonly<Pick<IntercomConnection, "syncStatus">>;
+type Replies = Readonly<Pick<ReplyTracker, "recordIncomingMessage">>;
 
 interface InboundOwners {
   readonly delivery: InboundDeliveryHandle;
+  readonly journal: Readonly<Pick<InboundJournal, "consume" | "owns">>;
   readonly replies: Replies;
   readonly wait: ReplyWaitHandle;
   readonly connection: Connection;
@@ -71,33 +73,6 @@ export class IntercomInbound {
     }
     return true;
   }
-  private async busyNonInteractive(
-    entry: InboundMessageEntry,
-    ctx: ExtensionContext,
-    generation: number,
-  ): Promise<void> {
-    if (entry.message.expectsReply !== true) {
-      this.owners.delivery.send(entry, "steer", generation);
-      return;
-    }
-    const active = this.owners.connection.active;
-    if (entry.message.replyTo !== undefined || active?.isConnected() !== true) {
-      return;
-    }
-    try {
-      const result = await active.send(entry.from.id, {
-        text: "This agent is running in non-interactive mode and cannot respond to intercom messages while it is working. It will continue its current task and exit when done.",
-        replyTo: entry.message.id,
-      });
-      if (result.delivered && this.lifecycle.live(ctx, generation)) {
-        this.owners.replies.markReplied(entry.message.id);
-        this.lifecycle.markActivity();
-        this.owners.connection.syncStatus();
-      }
-    } catch {
-      /* Best-effort busy reply; the non-interactive task must continue either way. */
-    }
-  }
   private async admit(
     entry: InboundMessageEntry,
     live: ExtensionContext,
@@ -108,7 +83,7 @@ export class IntercomInbound {
       return;
     }
     if (!this.lifecycle.isIdle(active)) {
-      await this.busy(entry, active, generation);
+      this.busy(entry, generation);
       return;
     }
     if (this.lifecycle.live(live, generation)) {
@@ -119,32 +94,33 @@ export class IntercomInbound {
       );
     }
   }
-  private async busy(
-    entry: InboundMessageEntry,
-    ctx: ExtensionContext,
-    generation: number,
-  ): Promise<void> {
+  private busy(entry: InboundMessageEntry, generation: number): void {
     const delivery = requestedDelivery(entry.message);
     if (delivery === "steer") {
       this.owners.delivery.send(entry, "steer", generation);
-      await this.owners.delivery.detach(entry, entry.message.expectsReply !== true);
       return;
     }
-    if (delivery === "queue" && entry.message.queueMode !== "replace") {
+    if (delivery === "queue") {
       this.owners.delivery.send(entry, "followUp", generation);
       return;
     }
-    if (delivery === "passive") {
-      this.owners.delivery.queue(entry, "passive");
-      return;
-    }
-    if (!ctx.hasUI) {
-      await this.busyNonInteractive(entry, ctx, generation);
-      return;
-    }
-    this.owners.delivery.queue(entry, "auto");
+    this.owners.delivery.queue(entry, "passive");
   }
+  /** Counted synchronously so a parking fence observes frames received before its ack. */
+  receiving = 0;
   async receive(ctx: ExtensionContext, from: SessionInfo, input: Message): Promise<void> {
+    this.receiving++;
+    try {
+      await this.receiveCounted(ctx, from, input);
+    } finally {
+      this.receiving--;
+    }
+  }
+  private async receiveCounted(
+    ctx: ExtensionContext,
+    from: SessionInfo,
+    input: Message,
+  ): Promise<void> {
     const generation = this.lifecycle.generation;
     const restore = this.owners.delivery.restoring;
     if (restore) {
@@ -154,10 +130,18 @@ export class IntercomInbound {
     if (!live) {
       return;
     }
+    if (input.guard && !this.lifecycle.accepts(input.guard)) {
+      return;
+    }
     // Peer metadata never grants user authority.
     const message = input.human ? { ...input, human: undefined } : input;
+    const entry = this.entry(from, message);
+    if (!this.owners.journal.owns(entry)) {
+      return;
+    }
     if (
       this.owners.wait.receive(from, message, () => {
+        this.owners.journal.consume(message.id);
         this.lifecycle.markActivity();
         this.owners.connection.syncStatus();
       })
@@ -167,7 +151,6 @@ export class IntercomInbound {
     this.owners.replies.recordIncomingMessage(from, message);
     this.lifecycle.markActivity();
     this.owners.connection.syncStatus();
-    const entry = this.entry(from, message);
     await this.admit(entry, live, generation);
   }
 }

package/src/pi-intercom/index.ts

@@ -13,6 +13,20 @@ 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 type { NativeHistory } from "./last-message.ts";
+
+/** The agent runtime answers for its exited parked child from the captured native session. */
+function parkedHistory(pi: ExtensionAPI, peer: string): Promise<NativeHistory | undefined> {
+  let history: Promise<NativeHistory | undefined> | undefined;
+  pi.events.emit(PARKED_HISTORY, {
+    peer,
+    reply: (found: Promise<NativeHistory | undefined>) => {
+      history = found;
+    },
+  });
+  return history ?? Promise.reject(new Error("No agent runtime owns parked history."));
+}
 
 export default function piIntercomExtension(pi: ExtensionAPI): void {
   const config = loadConfig();
@@ -23,6 +37,7 @@ export default function piIntercomExtension(pi: ExtensionAPI): void {
   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);
@@ -33,13 +48,19 @@ export default function piIntercomExtension(pi: ExtensionAPI): void {
         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 delivery = new InboundDeliveryOwner(pi, lifecycle, journal, {
     replies,
     syncStatus: () => connection.syncStatus(),
   });
+  lifecycle.registerContextEvents(() => connection.syncStatus());
   const inbound = new IntercomInbound(lifecycle, config, {
     delivery,
+    journal,
     replies,
     wait,
     connection,
@@ -56,4 +77,27 @@ export default function piIntercomExtension(pi: ExtensionAPI): void {
     wait,
   }).register();
   registerIntercomTools(pi, tools);
+  pi.events.on(PARK, (request) => {
+    if (isParkRequest(request)) {
+      request.reply(request.park ? connection.park() : connection.unpark());
+    }
+  });
+  // Native fork sleep readiness; it vetoes only this package's own parking, never other saves.
+  Reflect.apply(pi.on.bind(pi), undefined, [
+    "working_session_save",
+    () =>
+      !connection.parking
+        ? undefined
+        : {
+            blockers: [
+              inbound.receiving > 0 && "intercom is receiving a message",
+              journal.size > 0 && "intercom inbound messages await delivery",
+              replies.listPending().length > 0 && "intercom asks await replies",
+              wait.waiting && "intercom is waiting for a reply",
+              (delivery.restoring !== undefined || delivery.batching) &&
+                "intercom delivery is restoring",
+              connection.reconnected && "intercom reconnected while parking",
+            ].filter((blocker) => typeof blocker === "string"),
+          },
+  ]);
 }

package/src/pi-intercom/last-message.ts

@@ -1,26 +1,18 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { LastMessageQuery, LastMessageResult, SessionInfo } from "./types.ts";
+import {
+  isLastMessageQuery,
+  LAST_MESSAGE_PAGE_LIMIT,
+  type LastMessageQuery,
+  type LastMessageResult,
+  type SessionInfo,
+} from "./types.ts";
 
-type NativeHistory = ExtensionContext["sessionManager"];
-function validPage(offset: number, limit: number): boolean {
-  return (
-    Number.isSafeInteger(offset) &&
-    offset >= 0 &&
-    Number.isSafeInteger(limit) &&
-    limit >= 1 &&
-    limit <= 16384
-  );
-}
+export type NativeHistory = Pick<ExtensionContext["sessionManager"], "getBranch">;
 function completedResponse(
   manager: NativeHistory,
   entryId?: string,
 ): { readonly id: string; readonly text: string } | undefined {
-  let id = manager.getLeafId();
-  while (id !== null) {
-    const entry = manager.getEntry(id);
-    if (!entry) {
-      throw new Error("Native session history is unavailable.");
-    }
+  for (const entry of manager.getBranch().reverse()) {
     if (
       entry.type === "message" &&
       entry.message.role === "assistant" &&
@@ -35,7 +27,6 @@ function completedResponse(
           .join("\n"),
       };
     }
-    id = entry.parentId;
   }
   return;
 }
@@ -46,8 +37,8 @@ export function readLastMessage(
   query: LastMessageQuery,
 ): LastMessageResult {
   const offset = query.offset ?? 0;
-  const limit = query.limit ?? 16384;
-  if (!validPage(offset, limit)) {
+  const limit = query.limit ?? LAST_MESSAGE_PAGE_LIMIT;
+  if (!isLastMessageQuery({ offset, limit })) {
     return {
       error: "Invalid last response page: offset must be non-negative and limit must be 1–16384.",
     };

package/src/pi-intercom/lifecycle.ts

@@ -1,8 +1,28 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
 import type { IntercomConfig } from "./config.ts";
 import { buildPresenceIdentity, type IntercomLineage } from "./identity.ts";
 import { resolveSessionProjectId } from "./session-targets.ts";
-import type { SessionInfo } from "./types.ts";
+import {
+  isContextTarget,
+  type ContextTarget,
+  type DeliveryGuard,
+  type SessionInfo,
+} from "./types.ts";
+import { isRecord, safeLabel } from "./validation.ts";
+
+export function isContextRequest(value: unknown): value is Readonly<Record<string, unknown>> & {
+  readonly respond: (response: unknown) => void;
+} {
+  return isRecord(value) && typeof value.respond === "function";
+}
+
+type ContextSnapshot = Readonly<Record<keyof ContextTarget, string | null>> &
+  Pick<SessionInfo, "parentSessionId" | "applicationGuard"> & {
+    readonly version: 1;
+    readonly connected: boolean;
+    readonly guardedDelivery: 1 | null;
+  };
 
 /** Owns native context validity and occupancy, never journal or socket state. */
 export class IntercomLifecycle {
@@ -11,6 +31,10 @@ export class IntercomLifecycle {
   private model = "unknown";
   private disposed = true;
   private epoch = 0;
+  private incarnation: string | null = null;
+  private peerId: string | null = null;
+  private guardedDelivery = false;
+  private applicationGuard: string | undefined;
   private running = false;
   private activity = 0;
   private readonly tools = new Map<string, string>();
@@ -31,15 +55,97 @@ export class IntercomLifecycle {
   get toolCount(): number {
     return this.tools.size;
   }
+  registerContextEvents(sync: () => void): void {
+    this.pi.events.on("pi-intercom:context-query", (request) => this.contextRequest(request));
+    this.pi.events.on("pi-intercom:application-guard", (request) =>
+      this.contextRequest(request, sync),
+    );
+  }
+  private contextRequest(request: unknown, sync?: () => void): void {
+    if (!isContextRequest(request)) {
+      return;
+    }
+    if (request.version !== 1) {
+      request.respond({ error: "unsupported_version" });
+      return;
+    }
+    if (sync) {
+      if (
+        !isContextTarget(request.target) ||
+        !this.matches(request.target) ||
+        !(
+          request.revision === null ||
+          (typeof request.revision === "string" && safeLabel(request.revision))
+        )
+      ) {
+        request.respond({ error: "context_changed" });
+        return;
+      }
+      this.applicationGuard = request.revision === null ? undefined : request.revision;
+      sync();
+      this.publishContext();
+    }
+    request.respond(this.snapshot());
+  }
+  snapshot(): ContextSnapshot {
+    if (!this.live()) {
+      return {
+        version: 1,
+        rootSessionId: null,
+        peerId: null,
+        incarnation: null,
+        connected: false,
+        guardedDelivery: null,
+      } as const;
+    }
+    return {
+      version: 1,
+      rootSessionId: this.lineage?.rootSessionId ?? this.sessionId,
+      parentSessionId: this.lineage?.parentSessionId,
+      peerId: this.peerId,
+      incarnation: this.incarnation,
+      connected: this.peerId !== null,
+      guardedDelivery: this.guardedDelivery ? 1 : null,
+      applicationGuard: this.applicationGuard,
+    } as const;
+  }
+  private publishContext(): void {
+    this.pi.events.emit("pi-intercom:context-state", this.snapshot());
+  }
+  transport(peerId: string | null, guardedDelivery = false): void {
+    this.peerId = peerId;
+    this.guardedDelivery = guardedDelivery;
+    this.publishContext();
+  }
+  private matches(target: ContextTarget): boolean {
+    const current = this.snapshot();
+    return (
+      current.connected &&
+      current.rootSessionId === target.rootSessionId &&
+      current.peerId === target.peerId &&
+      current.incarnation === target.incarnation
+    );
+  }
+  accepts(guard: DeliveryGuard): boolean {
+    return (
+      this.guardedDelivery &&
+      this.lineage?.parentSessionId === undefined &&
+      this.matches(guard) &&
+      this.applicationGuard === guard.applicationGuard
+    );
+  }
   start(ctx: ExtensionContext): number {
     this.disposed = false;
     this.epoch += 1;
     this.context = ctx;
     this.sessionId = ctx.sessionManager.getSessionId();
+    this.incarnation = randomUUID();
+    this.applicationGuard = undefined;
     this.model = ctx.model?.id ?? "unknown";
     this.running = false;
     this.activity = 0;
     this.tools.clear();
+    this.transport(null);
     return this.epoch;
   }
   invalidate(): void {
@@ -47,6 +153,7 @@ export class IntercomLifecycle {
     this.epoch += 1;
     this.running = false;
     this.tools.clear();
+    this.publishContext();
   }
   clear(): void {
     this.context = null;
@@ -104,11 +211,7 @@ export class IntercomLifecycle {
   markActivity(): void {
     this.activity = Date.now();
   }
-  identity(sessionId: string): {
-    readonly name: string;
-    readonly rootSessionId: string;
-    readonly parentSessionId?: string;
-  } {
+  identity(sessionId: string): Pick<SessionInfo, "name" | "rootSessionId" | "parentSessionId"> {
     return {
       ...buildPresenceIdentity(this.pi, sessionId),
       rootSessionId: this.lineage?.rootSessionId ?? sessionId,
@@ -125,11 +228,9 @@ export class IntercomLifecycle {
       ? `${status} · ${this.config.status}`
       : status;
   }
-  health(pendingAsks: number): {
-    readonly pendingAsks: number;
-    readonly acceptsAsks: boolean;
-    readonly lastIntercomActivity: number;
-  } {
+  health(
+    pendingAsks: number,
+  ): Pick<SessionInfo, "pendingAsks" | "acceptsAsks" | "lastIntercomActivity"> {
     const live = this.live();
     return {
       pendingAsks,
@@ -142,12 +243,14 @@ export class IntercomLifecycle {
     if (!live || this.sessionId === null) {
       throw new Error("Intercom runtime not initialized");
     }
-    const cwd = live.cwd;
     return {
       ...this.identity(this.sessionId),
-      cwd,
+      incarnation: this.incarnation ?? undefined,
+      guardedDelivery: 1,
+      applicationGuard: this.applicationGuard,
+      cwd: live.cwd,
       model: this.model,
-      projectId: await resolveSessionProjectId(cwd),
+      projectId: await resolveSessionProjectId(live.cwd),
       lastSeen: Date.now(),
       status: this.status(),
       ...this.health(pendingAsks),

package/src/pi-intercom/outbound.ts

@@ -22,7 +22,7 @@ import { formatAttachments } from "./message-format.ts";
 import {
   AskDeliveryError,
   failureDetails,
-  replyFailureReason,
+  RecoveryError,
   type RecoveryAction,
 } from "./tool-results.ts";
 import { sendOptions, toolError, toolText } from "./tool-arguments.ts";
@@ -155,11 +155,10 @@ export class IntercomOutbound {
       }
       return this.sent(to, params, result);
     } catch (error) {
-      const text = errorMessage(error);
       return toolError(
-        `Failed to send: ${text}`,
+        `Failed to send: ${errorMessage(error)}`,
         failureDetails(
-          text.startsWith("Target ") ? "ambiguous_target" : "send_failed",
+          error instanceof RecoveryError ? error.code : "send_failed",
           [
             { action: "list" },
             { action: "send", guidance: "Retry with an exact active recipient target." },
@@ -225,17 +224,10 @@ export class IntercomOutbound {
       const result = this.deliveryFailure(to, error.result);
       return { ...result, details: { ...result.details, error: true } };
     }
-    const text = errorMessage(error);
-    let reason = "ask_failed";
-    if (text.startsWith("No reply from")) {
-      reason = "reply_timeout";
-    } else if (text.startsWith("Target ")) {
-      reason = "ambiguous_target";
-    }
     return toolError(
-      `Failed: ${text}`,
+      `Failed: ${errorMessage(error)}`,
       failureDetails(
-        reason,
+        error instanceof RecoveryError ? error.code : "ask_failed",
         [
           { action: "status" },
           { action: "list" },
@@ -409,8 +401,7 @@ export class IntercomOutbound {
     }
   }
   private replyFailure(error: unknown, replyTo: string | undefined): ToolResultLike {
-    const text = errorMessage(error);
-    const reason = replyFailureReason(text);
+    const reason = error instanceof RecoveryError ? error.code : "reply_failed";
     const actions: readonly RecoveryAction[] =
       reason === "no_pending_reply"
         ? [
@@ -423,7 +414,7 @@ export class IntercomOutbound {
           ]
         : [{ action: "pending" }, { action: "list" }];
     return toolError(
-      `Failed to reply: ${text}`,
+      `Failed to reply: ${errorMessage(error)}`,
       failureDetails(reason, actions, {
         error: true,
         ...((replyTo ?? "") !== "" ? { replyTo } : {}),

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

@@ -1,5 +1,6 @@
 import type { Message, SessionInfo } from "./types.ts";
 import { formatSessionTarget, resolveSessionTarget, shortSessionId } from "./session-targets.ts";
+import { RecoveryError } from "./tool-results.ts";
 
 export interface IntercomContext {
   readonly from: SessionInfo;
@@ -55,7 +56,7 @@ function matchingSender(
 ): readonly IntercomContext[] {
   const tooShort = tooShortSenderTargetMessage(contexts, to);
   if (tooShort !== null && tooShort !== "") {
-    throw new Error(tooShort);
+    throw new RecoveryError("ambiguous_reply_target", tooShort);
   }
   return resolveBySenderTarget(contexts, to);
 }
@@ -66,7 +67,7 @@ function explicitReply(
 ): IntercomContext {
   const target = contexts.find((context) => context.message.id === replyTo);
   if (!target) {
-    throw new Error(`No pending ask with replyTo "${replyTo}"`);
+    throw new RecoveryError("no_pending_reply", `No pending ask with replyTo "${replyTo}"`);
   }
   if (
     to !== "" &&
@@ -82,11 +83,12 @@ function replyBySender(contexts: readonly IntercomContext[], to: string): Interc
     return matches[0];
   }
   if (matches.length > 1) {
-    throw new Error(
+    throw new RecoveryError(
+      "ambiguous_reply_target",
       `Multiple pending asks from "${to}" — use one of: ${pendingSenderOptions(matches, contexts)}.`,
     );
   }
-  throw new Error(`No pending ask from "${to}"`);
+  throw new RecoveryError("no_pending_reply", `No pending ask from "${to}"`);
 }
 export class ReplyTracker {
   private readonly pendingAsks = new Map<string, IntercomContext>();
@@ -209,9 +211,9 @@ export class ReplyTracker {
       return pending[0];
     }
     if (pending.length === 0) {
-      throw new Error("No active intercom context to reply to");
+      throw new RecoveryError("no_pending_reply", "No active intercom context to reply to");
     }
-    throw new Error("Multiple pending asks — specify `to`");
+    throw new RecoveryError("ambiguous_reply_target", "Multiple pending asks — specify `to`");
   }
 
   markReplied(replyTo: string): void {

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 } from "./tool-results.ts";
+import { AskDeliveryError, RecoveryError } from "./tool-results.ts";
 
 type Lifecycle = Readonly<Pick<IntercomLifecycle, "markActivity">>;
 interface ReplyWaiter {
@@ -71,7 +71,8 @@ export class ReplyWait {
       const { from, replyTo, signal } = options;
       const timeout = setTimeout(() => {
         this.reject(
-          new Error(
+          new RecoveryError(
+            "reply_timeout",
             `No reply from "${from}" within ${Math.max(1, Math.round(this.timeoutMs / 60000))} minute(s)`,
           ),
         );

package/src/pi-intercom/runtime-types.ts

@@ -17,7 +17,6 @@ export type InboundCheckpoint =
       readonly messageId: string;
       readonly stage: PendingInboundMessage["stage"] | "discarded" | "reply-retired";
     };
-export type RequestedDelivery = MessageDelivery | "auto";
 export type InboundDelivery = "trigger" | "followUp" | "steer" | "passive";
 export type IntercomSessionScope = "project" | "all";
 export interface ToolResultLike {

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

@@ -2,17 +2,20 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { IntercomTools } from "./tools.ts";
 import { throwIfToolError } from "./tool-results.ts";
 import { intercomSchema } from "./tool-schemas.ts";
+import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.ts";
 
 export function registerIntercomTools(
   pi: ExtensionAPI,
   tools: Readonly<Pick<IntercomTools, "execute">>,
 ): void {
+  registerCompactMessages(pi, ["intercom_message", "subagent-human-message"]);
   pi.registerTool({
     name: "intercom",
     label: "Intercom",
     description:
-      "Discover and message connected Pi sessions in your collaboration group; main sessions can also reach other mains, across projects. Use list for unambiguous targets. Send defaults to steer at the next tool boundary; queue defers; passive never wakes the model. Ask waits for a correlated reply; reply answers the active or single pending ask (specify replyTo when ambiguous). Pending lists asks; status shows connection and inbound queue state. Last reads a peer's original completed assistant response without waking it; page using entryId and nextOffset. Broker acceptance is not recipient persistence, consumption, or task completion.",
+      "Message connected Pi sessions in your group; mains also reach other mains across projects. List shows target IDs. Ask waits for a correlated reply; reply answers the active or sole pending ask. Pending lists asks; status shows connection and inbound queue. Last pages a peer's last completed response without waking it. Broker acceptance is not recipient persistence, consumption or completion.",
     parameters: intercomSchema,
+    renderResult: renderCompactResult,
     async execute(_id, params, signal, _update, ctx) {
       const result = throwIfToolError(await tools.execute(params, signal, ctx));
       return { content: [...result.content], details: result.details };

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

@@ -1,5 +1,10 @@
 import type { SendResult } from "./types.ts";
 import type { ToolResultLike } from "./runtime-types.ts";
+type RecoveryCode =
+  | "ambiguous_target"
+  | "reply_timeout"
+  | "no_pending_reply"
+  | "ambiguous_reply_target";
 export interface RecoveryAction {
   readonly action: "list" | "pending" | "send" | "status";
   readonly guidance?: string;
@@ -11,16 +16,12 @@ export function failureDetails(
 ): Readonly<Record<string, unknown>> {
   return { ...details, reasonCode, nextActions };
 }
-export function replyFailureReason(
-  message: string,
-): "no_pending_reply" | "ambiguous_reply_target" | "reply_failed" {
-  if (message.startsWith("No active intercom context") || message.startsWith("No pending ask")) {
-    return "no_pending_reply";
-  }
-  if (message.startsWith("Multiple pending asks") || message.includes("too short")) {
-    return "ambiguous_reply_target";
+export class RecoveryError extends Error {
+  readonly code: RecoveryCode;
+  constructor(code: RecoveryCode, message: string) {
+    super(message);
+    this.code = code;
   }
-  return "reply_failed";
 }
 export function firstTextContent(result: {
   readonly content?: readonly { readonly type: string; readonly text?: string }[];