@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/src/pi-intercom/connection.ts

@@ -4,28 +4,40 @@ import type { IntercomTransport } from "./transport.ts";
 import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
 import type { IntercomConfig } from "./config.ts";
 import type { IntercomLifecycle } from "./lifecycle.ts";
-import type { LastMessageQuery, Message, SessionInfo } from "./types.ts";
-import { readLastMessage } from "./last-message.ts";
+import type { Message, SessionInfo, ReceiptQuery, ReceiptResult } from "./types.ts";
+import type { NativeReadQuery } from "./broker/last.ts";
+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";
 
-type Lifecycle = Readonly<
-  Pick<
-    IntercomLifecycle,
-    "currentSessionId" | "generation" | "health" | "identity" | "live" | "registration" | "status"
-  >
->;
+type Lifecycle = Pick<
+  Readonly<IntercomLifecycle>,
+  "currentSessionId" | "generation" | "health" | "identity" | "live" | "registration" | "status"
+> &
+  Pick<Readonly<IntercomLifecycle>, "snapshot" | "transport">;
 
 interface ConnectionHooks {
   readonly restoring: () => Promise<void> | undefined;
   readonly pendingAsks: () => number;
+  readonly receipt: (query: ReceiptQuery) => ReceiptResult;
   readonly incoming: (ctx: ExtensionContext, from: SessionInfo, message: Message) => Promise<void>;
   readonly peerLeft: (id: string) => void;
   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;
+}
+interface LastRequest {
+  readonly requestId: string;
+  readonly query: NativeReadQuery;
+  readonly parked?: SessionInfo;
 }
 /** Owns socket registration, coalesced connects and the reconnect/startup timers. */
 export class IntercomConnection {
   private client: IntercomClient | null = null;
+  /** The transport whose broker retains this actor's input while it parks. */
+  private parked: IntercomClient | null = null;
   private reconnectTimer: NodeJS.Timeout | null = null;
   private startupTimer: NodeJS.Timeout | null = null;
   private connecting: Promise<IntercomTransport> | null = null;
@@ -42,6 +54,22 @@ export class IntercomConnection {
   get active(): IntercomTransport | null {
     return this.client;
   }
+  async park(): Promise<boolean> {
+    const client = this.client;
+    this.parked = client !== null && (await client.park().catch(() => false)) ? client : null;
+    return this.parked !== null && this.parked === this.client;
+  }
+  get parking(): boolean {
+    return this.parked !== null;
+  }
+  get reconnected(): boolean {
+    return this.client !== null && this.client !== this.parked;
+  }
+  unpark(): Promise<boolean> {
+    const client = this.parked === this.client ? this.client : null;
+    this.parked = null;
+    return client?.park(false).catch(() => false) ?? Promise.resolve(false);
+  }
   start(ctx: ExtensionContext, generation: number): void {
     this.attempt = 0;
     this.clearTimers();
@@ -113,44 +141,71 @@ export class IntercomConnection {
       this.client.updatePresence({
         status: this.lifecycle.status(),
         ...this.lifecycle.health(this.hooks.pendingAsks()),
+        applicationGuard: this.lifecycle.snapshot().applicationGuard ?? null,
       });
     }
   }
+  private answerLast(next: IntercomClient, request: LastRequest): void {
+    const ctx = this.lifecycle.live();
+    const id = next.sessionId;
+    if (this.client !== next || !ctx || id === null) {
+      next.respondLast(request.requestId, { error: "Intercom runtime no longer active" });
+      return;
+    }
+    const { parked, query } = request;
+    if ("messageId" in query) {
+      // The broker refuses receipt reads of an exited parked child before relaying them.
+      next.respondLast(
+        request.requestId,
+        parked ? { error: "publication_unavailable" } : this.hooks.receipt(query),
+      );
+      return;
+    }
+    if (parked) {
+      this.hooks
+        .parkedHistory(parked)
+        .then((history) =>
+          history
+            ? readLastMessage(history, parked, query)
+            : { error: "Parked session history is unavailable." },
+        )
+        .catch((error: unknown) => ({ error: asError(error).message }))
+        .then((result) => {
+          next.respondLast(request.requestId, result);
+        })
+        .catch(() => {
+          /* The requester's broker timeout reports a lost transport. */
+        });
+      return;
+    }
+    try {
+      next.respondLast(
+        request.requestId,
+        readLastMessage(
+          ctx.sessionManager,
+          {
+            id,
+            ...this.lifecycle.identity(ctx.sessionManager.getSessionId()),
+            cwd: ctx.cwd,
+            model: ctx.model?.id ?? "unknown",
+            status: this.lifecycle.status(),
+          },
+          query,
+        ),
+      );
+    } catch (error) {
+      next.respondLast(request.requestId, { error: asError(error).message });
+    }
+  }
   private createClient(): IntercomClient {
     const next = new IntercomClient({
       sendTimeoutMs: this.config.sendTimeoutMs,
       listTimeoutMs: this.config.listTimeoutMs,
     });
     this.client = next;
-    next.on(
-      "last_request",
-      (request: { readonly requestId: string; readonly query: LastMessageQuery }) => {
-        const ctx = this.lifecycle.live();
-        const id = next.sessionId;
-        if (this.client !== next || !ctx || id === null) {
-          next.respondLast(request.requestId, { error: "Intercom runtime no longer active" });
-          return;
-        }
-        try {
-          next.respondLast(
-            request.requestId,
-            readLastMessage(
-              ctx.sessionManager,
-              {
-                id,
-                ...this.lifecycle.identity(ctx.sessionManager.getSessionId()),
-                cwd: ctx.cwd,
-                model: ctx.model?.id ?? "unknown",
-                status: this.lifecycle.status(),
-              },
-              request.query,
-            ),
-          );
-        } catch (error) {
-          next.respondLast(request.requestId, { error: asError(error).message });
-        }
-      },
-    );
+    next.on("last_request", (request: LastRequest) => {
+      this.answerLast(next, request);
+    });
     next.on("message", (from: SessionInfo, message: Message) => {
       const ctx = this.lifecycle.live();
       if (this.client !== next || !ctx) {
@@ -160,6 +215,11 @@ export class IntercomConnection {
         console.error("Intercom inbound delivery failed:", error);
       });
     });
+    next.on("wake", (peer: string) => {
+      if (this.client === next) {
+        this.hooks.wake(peer);
+      }
+    });
     next.on("session_left", (id: string) => {
       if (this.client !== next) {
         return;
@@ -172,6 +232,7 @@ export class IntercomConnection {
       }
       this.hooks.disconnected(error);
       this.client = null;
+      this.lifecycle.transport(null);
       this.clearReconnect();
       this.scheduleReconnect();
     });
@@ -197,6 +258,7 @@ export class IntercomConnection {
         throw new Error("Intercom runtime no longer active");
       }
       this.client = next;
+      this.lifecycle.transport(next.sessionId, next.supportsGuardedDelivery);
       this.syncIdentity(ctx.sessionManager.getSessionId());
       this.attempt = 0;
       return next;
@@ -279,12 +341,14 @@ export async function resolveConnectedTarget(
     return resolution.target.id;
   }
   if (resolution.status === "ambiguous") {
-    throw new Error(
+    throw new RecoveryError(
+      "ambiguous_target",
       `Target "${name}" matches multiple sessions. Use one of these targets: ${formatTargetOptions(resolution.matches, sessions)}.`,
     );
   }
   if (resolution.status === "prefix_too_short") {
-    throw new Error(
+    throw new RecoveryError(
+      "ambiguous_target",
       `Target "${name}" is too short. Use the displayed target from intercom list, such as ${formatTargetOptions(resolution.matches, sessions)}.`,
     );
   }

package/src/pi-intercom/identity.ts

@@ -4,20 +4,23 @@ export interface IntercomLineage {
   readonly rootSessionId: string;
   readonly parentSessionId: string;
 }
+// Launches set both variables to the parent's exact native session ID. Absence means a main;
+// anything else is refused, never normalized into a different identity.
 export function readIntercomLineage(): IntercomLineage | undefined {
-  const rootSessionId = process.env.PI_INTERCOM_ROOT_SESSION_ID?.trim();
-  const parentSessionId = process.env.PI_INTERCOM_PARENT_SESSION_ID?.trim();
+  const rootSessionId = process.env.PI_INTERCOM_ROOT_SESSION_ID;
+  const parentSessionId = process.env.PI_INTERCOM_PARENT_SESSION_ID;
   if (rootSessionId === undefined && parentSessionId === undefined) {
     return;
   }
   if (
     rootSessionId === undefined ||
-    parentSessionId === undefined ||
     rootSessionId === "" ||
-    parentSessionId === "" ||
+    rootSessionId !== rootSessionId.trim() ||
     rootSessionId !== parentSessionId
   ) {
-    throw new Error("Intercom child launch requires matching root and parent native session IDs.");
+    throw new Error(
+      "Child launch requires identical, unpadded root and parent native session IDs.",
+    );
   }
   return { rootSessionId, parentSessionId };
 }

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

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { IntercomLifecycle } from "./lifecycle.ts";
 import type { InboundJournal } from "./inbound-journal.ts";
@@ -9,10 +8,9 @@ import type {
   PendingInboundMessage,
 } from "./runtime-types.ts";
 import { requestedDelivery } from "./inbound-record.ts";
-import { isRecord } from "./validation.ts";
 import { runCooperatively } from "../shared/cooperative.ts";
 
-type Lifecycle = Readonly<Pick<IntercomLifecycle, "generation" | "isIdle" | "live" | "toolCount">>;
+type Lifecycle = Pick<Readonly<IntercomLifecycle>, "generation" | "isIdle" | "live" | "toolCount">;
 type Journal = Readonly<
   Pick<
     InboundJournal,
@@ -121,6 +119,9 @@ export class InboundDeliveryOwner {
     flushDelivery: PendingInboundMessage["flushDelivery"] = "auto",
     delayMs = 200,
   ): void {
+    if (!this.journal.owns(entry)) {
+      return;
+    }
     this.journal.remember(entry, "queued", flushDelivery);
     this.hooks.syncStatus();
     this.schedule(delayMs);
@@ -153,10 +154,7 @@ export class InboundDeliveryOwner {
   private triggerIndex(entries: readonly PendingInboundMessage[]): number {
     const canTrigger = (entry: PendingInboundMessage) =>
       entry.flushDelivery !== "passive" && requestedDelivery(entry.message) !== "passive";
-    const ask = entries.findIndex(
-      (entry) => canTrigger(entry) && entry.message.expectsReply === true,
-    );
-    return ask === -1 ? entries.findIndex(canTrigger) : ask;
+    return entries.findLastIndex(canTrigger);
   }
   private *sendTriggerLast(
     entries: readonly PendingInboundMessage[],
@@ -170,14 +168,19 @@ export class InboundDeliveryOwner {
     }
     const index = this.triggerIndex(rest);
     const trigger = index === -1 ? undefined : rest.splice(index, 1)[0];
-    if (trigger && this.journal.get(trigger.message.id) === trigger) {
-      this.hooks.replies.queueTurnContext({ ...trigger, receivedAt: Date.now() });
+    const replyTarget = entries.find((entry) => entry.message.expectsReply === true) ?? trigger;
+    if (replyTarget && this.journal.get(replyTarget.message.id) === replyTarget) {
+      this.hooks.replies.queueTurnContext({ ...replyTarget, receivedAt: Date.now() });
     }
     for (const entry of rest) {
       if (!this.live(generation)) {
         return;
       }
-      this.send(entry, entry.flushDelivery === "steer" ? "steer" : "followUp", generation);
+      this.send(
+        entry,
+        requestedDelivery(entry.message) === "queue" ? "followUp" : "steer",
+        generation,
+      );
       yield;
     }
     if (trigger) {
@@ -202,7 +205,6 @@ export class InboundDeliveryOwner {
   private *sendSteers(
     entries: readonly PendingInboundMessage[],
     generation: number,
-    onDetach: (task: Promise<boolean>) => void,
   ): Generator<void, void> {
     for (const entry of entries) {
       if (!this.live(generation)) {
@@ -212,9 +214,6 @@ export class InboundDeliveryOwner {
         continue;
       }
       this.send(entry, "steer", generation);
-      if (requestedDelivery(entry.message) === "steer") {
-        onDetach(this.detach(entry, entry.message.expectsReply !== true));
-      }
       yield;
     }
   }
@@ -243,15 +242,7 @@ export class InboundDeliveryOwner {
       this.schedule(500);
       return;
     }
-    return this.runBatch(async () => {
-      const detachments: Promise<boolean>[] = [];
-      await runCooperatively(
-        this.sendSteers(steers, generation, (task) => {
-          detachments.push(task);
-        }),
-      );
-      await Promise.all(detachments);
-    }, generation);
+    return this.runBatch(() => runCooperatively(this.sendSteers(steers, generation)), generation);
   }
   private messageOptions(delivery: InboundDelivery): {
     readonly triggerTurn?: boolean;
@@ -297,57 +288,20 @@ export class InboundDeliveryOwner {
     }
   }
   private nativeMessage(entry: InboundMessageEntry): Parameters<ExtensionAPI["sendMessage"]>[0] {
-    const sender =
-      entry.from.name === undefined || entry.from.name === ""
-        ? entry.from.id.slice(0, 8)
-        : entry.from.name;
+    const sender = entry.from.name ?? entry.from.id.slice(0, 8);
     const command = entry.replyCommand ?? "";
     const reply = command === "" ? "" : `\n\nTo reply, use the intercom tool: ${command}`;
+    const hint = entry.message.replyHint;
+    const publication = hint
+      ? `\n\nTo publish a correlated reply, use ${hint.tool} with commandId ${hint.commandId}. This is not an intercom ask.`
+      : "";
     return {
       customType: "intercom_message",
-      content: `**📨 From ${sender}** (Native session cwd: ${entry.from.cwd})${reply}\n\n${entry.bodyText}`,
+      content: `**📨 From ${sender}** (Native session cwd: ${entry.from.cwd})${reply}${publication}\n\n${entry.bodyText}`,
       display: true,
       details: { ...entry, bodyText: entry.bodyText },
     };
   }
-  async detach(entry: InboundMessageEntry, attention = false): Promise<boolean> {
-    if (!attention && entry.message.expectsReply !== true) {
-      return false;
-    }
-    const requestId = randomUUID();
-    return await new Promise((resolve) => {
-      let settled = false;
-
-      const finish = (accepted: boolean) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        clearTimeout(timer);
-        unsubscribe();
-        resolve(accepted);
-      };
-      const timer = setTimeout(() => finish(false), 500);
-      timer.unref();
-      const unsubscribe = this.pi.events.on("pi-intercom:detach-response", (payload: unknown) => {
-        if (isRecord(payload) && payload.requestId === requestId) {
-          finish(payload.accepted === true);
-        }
-      });
-      try {
-        this.pi.events.emit("pi-intercom:detach-request", {
-          requestId,
-          ...(attention ? { reason: "attention" } : {}),
-        });
-        // Owned waits answer ordinary attention synchronously; an unanswered probe completes now.
-        if (attention) {
-          finish(false);
-        }
-      } catch {
-        finish(false);
-      }
-    });
-  }
   async redeliver(ctx: ExtensionContext, generation: number): Promise<void> {
     if (this.batchTask) {
       await this.batchTask;

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

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
-import type { IntercomLifecycle } from "./lifecycle.ts";
+import { createHash } from "node:crypto";
+import { isContextRequest, type IntercomLifecycle } from "./lifecycle.ts";
 import type { ReplyTracker } from "./reply-tracker.ts";
 import {
   INBOUND_CHECKPOINT_TYPE,
@@ -7,7 +8,13 @@ import {
   type InboundMessageEntry,
   type PendingInboundMessage,
 } from "./runtime-types.ts";
-import { isInboundCheckpoint } from "./inbound-record.ts";
+import { isInboundCheckpoint, publicationMetadata, requestedDelivery } from "./inbound-record.ts";
+import {
+  isReceiptQuery,
+  type NativeReceipt,
+  type ReceiptQuery,
+  type ReceiptResult,
+} from "./types.ts";
 import { inboundIdFromCustomMessage } from "./message-format.ts";
 import { isRecord } from "./validation.ts";
 
@@ -29,6 +36,85 @@ export class InboundJournal {
     this.pi = pi;
     this.lifecycle = lifecycle;
     this.replies = replies;
+    pi.events.on("pi-intercom:provenance-query", (request) => {
+      if (!isContextRequest(request)) {
+        return;
+      }
+      request.respond(
+        request.version === 1 && isReceiptQuery(request)
+          ? this.receipt(request)
+          : { error: "publication_unavailable" },
+      );
+    });
+  }
+  receipt(query: ReceiptQuery): ReceiptResult {
+    const ctx = this.lifecycle.live();
+    if (!ctx || ctx.sessionManager.getSessionId() !== query.rootSessionId) {
+      return { error: "publication_unavailable" };
+    }
+    let receipt: NativeReceipt | undefined;
+    for (const item of ctx.sessionManager.getEntries()) {
+      receipt = this.receiptEntry(receipt, query, item);
+    }
+    return receipt ? { receipt } : { error: "receipt_not_found" };
+  }
+  private receiptEntry(
+    receipt: NativeReceipt | undefined,
+    query: ReceiptQuery,
+    item: SessionEntry,
+  ): NativeReceipt | undefined {
+    if (
+      item.type === "custom" &&
+      item.customType === INBOUND_CHECKPOINT_TYPE &&
+      isInboundCheckpoint(item.data) &&
+      item.data.sessionId === query.rootSessionId
+    ) {
+      return this.receiptCheckpoint(receipt, query, item.id, item.data);
+    }
+    return receipt && inboundIdFromCustomMessage(item) === query.messageId
+      ? { ...receipt, placementEntryId: item.id }
+      : receipt;
+  }
+  private receiptCheckpoint(
+    receipt: NativeReceipt | undefined,
+    query: ReceiptQuery,
+    entryId: string,
+    data: InboundCheckpoint,
+  ): NativeReceipt | undefined {
+    if ("entry" in data) {
+      if (receipt || data.entry.message.id !== query.messageId) {
+        return receipt;
+      }
+      const { from, message, stage, receivedAt } = data.entry;
+      return {
+        version: 1,
+        rootSessionId: query.rootSessionId,
+        messageId: query.messageId,
+        sender: {
+          peerId: from.id,
+          rootSessionId: from.rootSessionId,
+          incarnation: from.incarnation,
+        },
+        textSha256: createHash("sha256").update(message.content.text, "utf8").digest("hex"),
+        delivery: requestedDelivery(message),
+        ...publicationMetadata(message),
+        checkpointEntryId: entryId,
+        receivedAt,
+        queued: stage === "queued",
+        nativeHandoff: stage === "native",
+        placementEntryId: null,
+        discarded: false,
+      };
+    }
+    if (!receipt || data.messageId !== query.messageId) {
+      return receipt;
+    }
+    return {
+      ...receipt,
+      queued: receipt.queued || data.stage === "queued",
+      nativeHandoff: receipt.nativeHandoff || data.stage === "native",
+      discarded: receipt.discarded || data.stage === "discarded",
+    };
   }
   peerLeft(id: string): void {
     for (const pending of this.replies.listPending()) {
@@ -39,7 +125,7 @@ export class InboundJournal {
     this.replies.expireSender(id);
     for (const pending of this.queued()) {
       if (pending.from.id === id && pending.message.expectsReply === true) {
-        this.pending.delete(pending.message.id);
+        this.consume(pending.message.id);
         this.checkpoint({ messageId: pending.message.id, stage: "discarded" });
       }
     }
@@ -57,7 +143,10 @@ export class InboundJournal {
     return this.pending.get(id);
   }
   owns(entry: InboundMessageEntry): boolean {
-    return !("stage" in entry) || this.pending.get(entry.message.id) === entry;
+    const id = entry.message.id;
+    return "stage" in entry
+      ? this.pending.get(id) === entry
+      : !this.pending.has(id) && !this.consumed.has(id);
   }
   checkpoint(update: InboundCheckpoint): void {
     const sessionId = this.lifecycle.currentSessionId;
@@ -96,7 +185,7 @@ export class InboundJournal {
           pending.from.id === entry.from.id &&
           pending.message.threadId === entry.message.threadId
         ) {
-          this.pending.delete(pending.message.id);
+          this.consume(pending.message.id);
           this.replies.markReplied(pending.message.id);
         }
       }
@@ -164,7 +253,7 @@ export class InboundJournal {
       return;
     }
     if (data.stage === "discarded") {
-      this.pending.delete(data.messageId);
+      this.consume(data.messageId);
       this.replies.markReplied(data.messageId);
       return;
     }
@@ -192,6 +281,13 @@ export class InboundJournal {
     if (item.customType === "intercom_sent") {
       this.restoreSent(item.data);
     }
+    if (
+      item.customType === "intercom_received" &&
+      isRecord(item.data) &&
+      typeof item.data.messageId === "string"
+    ) {
+      this.consume(item.data.messageId);
+    }
   }
   private restoreSent(data: unknown): void {
     if (
@@ -226,7 +322,7 @@ export class InboundJournal {
       (entry.type === "custom_message" &&
         ["intercom_message", "subagent-human-message"].includes(entry.customType)) ||
       (entry.type === "custom" &&
-        [INBOUND_CHECKPOINT_TYPE, "intercom_sent"].includes(entry.customType))
+        [INBOUND_CHECKPOINT_TYPE, "intercom_sent", "intercom_received"].includes(entry.customType))
     );
   }
   private recentEntries(ctx: ExtensionContext, fullScan: boolean): readonly SessionEntry[] {

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

@@ -1,16 +1,31 @@
-import { isMessage, isSessionRegistration, type Message } from "./types.ts";
+import { isMessage, isSessionRegistration, type Message, type MessageDelivery } from "./types.ts";
 import type {
   InboundCheckpoint,
   InboundMessageEntry,
   PendingInboundMessage,
-  RequestedDelivery,
 } from "./runtime-types.ts";
 import { finiteNumber, isRecord } from "./validation.ts";
-export function requestedDelivery(message: Message): RequestedDelivery {
+
+export function publicationMetadata(message: Message): Pick<Message, "guard" | "replyHint"> {
+  return {
+    guard: message.guard && {
+      rootSessionId: message.guard.rootSessionId,
+      peerId: message.guard.peerId,
+      incarnation: message.guard.incarnation,
+      applicationGuard: message.guard.applicationGuard,
+    },
+    replyHint: message.replyHint && {
+      tool: message.replyHint.tool,
+      commandId: message.replyHint.commandId,
+      commandFingerprint: message.replyHint.commandFingerprint,
+    },
+  };
+}
+export function requestedDelivery(message: Message): MessageDelivery {
   if (message.passive === true || message.delivery === "passive") {
     return "passive";
   }
-  return message.delivery ?? (message.expectsReply === true ? "auto" : "steer");
+  return message.delivery ?? "steer";
 }
 function isLocalJournalMessage(value: unknown): value is Message {
   if (!isRecord(value) || !isRecord(value.content)) {
@@ -32,6 +47,8 @@ function isLocalJournalMessage(value: unknown): value is Message {
       "queueMode",
       "threadId",
       "passive",
+      "guard",
+      "replyHint",
     ].every((key) => value[key] === undefined)
   );
 }