@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/pi-intercom/identity.js

@@ -1,15 +1,16 @@
+// 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() {
-    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/dist/pi-intercom/inbound-delivery.js

@@ -1,6 +1,4 @@
-import { randomUUID } from "node:crypto";
 import { requestedDelivery } from "./inbound-record.js";
-import { isRecord } from "./validation.js";
 import { runCooperatively } from "../shared/cooperative.js";
 /** Owns cooperative inbound batches, restoration and the flush timer. */
 export class InboundDeliveryOwner {
@@ -83,6 +81,9 @@ export class InboundDeliveryOwner {
         this.timer.unref();
     }
     queue(entry, flushDelivery = "auto", delayMs = 200) {
+        if (!this.journal.owns(entry)) {
+            return;
+        }
         this.journal.remember(entry, "queued", flushDelivery);
         this.hooks.syncStatus();
         this.schedule(delayMs);
@@ -112,8 +113,7 @@ export class InboundDeliveryOwner {
     }
     triggerIndex(entries) {
         const canTrigger = (entry) => 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);
     }
     *sendTriggerLast(entries, generation) {
         const passives = entries.filter((entry) => entry.flushDelivery === "passive");
@@ -124,14 +124,15 @@ 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) {
@@ -150,7 +151,7 @@ export class InboundDeliveryOwner {
     live(generation) {
         return this.lifecycle.generation === generation && this.lifecycle.live() !== null;
     }
-    *sendSteers(entries, generation, onDetach) {
+    *sendSteers(entries, generation) {
         for (const entry of entries) {
             if (!this.live(generation)) {
                 return;
@@ -159,9 +160,6 @@ export class InboundDeliveryOwner {
                 continue;
             }
             this.send(entry, "steer", generation);
-            if (requestedDelivery(entry.message) === "steer") {
-                onDetach(this.detach(entry, entry.message.expectsReply !== true));
-            }
             yield;
         }
     }
@@ -184,13 +182,7 @@ export class InboundDeliveryOwner {
             this.schedule(500);
             return;
         }
-        return this.runBatch(async () => {
-            const detachments = [];
-            await runCooperatively(this.sendSteers(steers, generation, (task) => {
-                detachments.push(task);
-            }));
-            await Promise.all(detachments);
-        }, generation);
+        return this.runBatch(() => runCooperatively(this.sendSteers(steers, generation)), generation);
     }
     messageOptions(delivery) {
         if (delivery === "trigger") {
@@ -229,56 +221,20 @@ export class InboundDeliveryOwner {
         }
     }
     nativeMessage(entry) {
-        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, attention = false) {
-        if (!attention && entry.message.expectsReply !== true) {
-            return false;
-        }
-        const requestId = randomUUID();
-        return await new Promise((resolve) => {
-            let settled = false;
-            const finish = (accepted) => {
-                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) => {
-                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, generation) {
         if (this.batchTask) {
             await this.batchTask;

package/dist/pi-intercom/inbound-journal.js

@@ -1,5 +1,8 @@
+import { createHash } from "node:crypto";
+import { isContextRequest } from "./lifecycle.js";
 import { INBOUND_CHECKPOINT_TYPE, } from "./runtime-types.js";
-import { isInboundCheckpoint } from "./inbound-record.js";
+import { isInboundCheckpoint, publicationMetadata, requestedDelivery } from "./inbound-record.js";
+import { isReceiptQuery, } from "./types.js";
 import { inboundIdFromCustomMessage } from "./message-format.js";
 import { isRecord } from "./validation.js";
 export class InboundJournal {
@@ -14,6 +17,72 @@ 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) {
+        const ctx = this.lifecycle.live();
+        if (!ctx || ctx.sessionManager.getSessionId() !== query.rootSessionId) {
+            return { error: "publication_unavailable" };
+        }
+        let receipt;
+        for (const item of ctx.sessionManager.getEntries()) {
+            receipt = this.receiptEntry(receipt, query, item);
+        }
+        return receipt ? { receipt } : { error: "receipt_not_found" };
+    }
+    receiptEntry(receipt, query, item) {
+        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;
+    }
+    receiptCheckpoint(receipt, query, entryId, data) {
+        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) {
         for (const pending of this.replies.listPending()) {
@@ -24,7 +93,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" });
             }
         }
@@ -42,7 +111,10 @@ export class InboundJournal {
         return this.pending.get(id);
     }
     owns(entry) {
-        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) {
         const sessionId = this.lifecycle.currentSessionId;
@@ -77,7 +149,7 @@ export class InboundJournal {
                 if (pending.stage === "queued" &&
                     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);
                 }
             }
@@ -135,7 +207,7 @@ export class InboundJournal {
             return;
         }
         if (data.stage === "discarded") {
-            this.pending.delete(data.messageId);
+            this.consume(data.messageId);
             this.replies.markReplied(data.messageId);
             return;
         }
@@ -163,6 +235,11 @@ 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);
+        }
     }
     restoreSent(data) {
         if (isRecord(data) &&
@@ -194,7 +271,7 @@ export class InboundJournal {
         return ((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)));
     }
     recentEntries(ctx, fullScan) {
         if (fullScan) {

package/dist/pi-intercom/inbound-record.js

@@ -1,10 +1,25 @@
 import { isMessage, isSessionRegistration } from "./types.js";
 import { finiteNumber, isRecord } from "./validation.js";
+export function publicationMetadata(message) {
+    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) {
     if (message.passive === true || message.delivery === "passive") {
         return "passive";
     }
-    return message.delivery ?? (message.expectsReply === true ? "auto" : "steer");
+    return message.delivery ?? "steer";
 }
 function isLocalJournalMessage(value) {
     if (!isRecord(value) || !isRecord(value.content)) {
@@ -25,6 +40,8 @@ function isLocalJournalMessage(value) {
             "queueMode",
             "threadId",
             "passive",
+            "guard",
+            "replyHint",
         ].every((key) => value[key] === undefined));
 }
 function isJournalMessage(value, sender) {

package/dist/pi-intercom/inbound.js

@@ -45,65 +45,43 @@ export class IntercomInbound {
         }
         return true;
     }
-    async busyNonInteractive(entry, ctx, generation) {
-        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. */
-        }
-    }
     async admit(entry, live, generation) {
         const active = this.lifecycle.live(live, generation);
         if (!active || this.queueAdmission(entry, active)) {
             return;
         }
         if (!this.lifecycle.isIdle(active)) {
-            await this.busy(entry, active, generation);
+            this.busy(entry, generation);
             return;
         }
         if (this.lifecycle.live(live, generation)) {
             this.owners.delivery.send(entry, requestedDelivery(entry.message) === "passive" ? "passive" : "trigger", generation);
         }
     }
-    async busy(entry, ctx, generation) {
+    busy(entry, generation) {
         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;
+        this.owners.delivery.queue(entry, "passive");
+    }
+    /** Counted synchronously so a parking fence observes frames received before its ack. */
+    receiving = 0;
+    async receive(ctx, from, input) {
+        this.receiving++;
+        try {
+            await this.receiveCounted(ctx, from, input);
         }
-        if (!ctx.hasUI) {
-            await this.busyNonInteractive(entry, ctx, generation);
-            return;
+        finally {
+            this.receiving--;
         }
-        this.owners.delivery.queue(entry, "auto");
     }
-    async receive(ctx, from, input) {
+    async receiveCounted(ctx, from, input) {
         const generation = this.lifecycle.generation;
         const restore = this.owners.delivery.restoring;
         if (restore) {
@@ -113,9 +91,17 @@ 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();
         })) {
@@ -124,7 +110,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/dist/pi-intercom/index.js

@@ -12,6 +12,18 @@ import { IntercomInspection } from "./inspection.js";
 import { IntercomTools } from "./tools.js";
 import { IntercomSessionEvents } from "./session-events.js";
 import { registerIntercomTools } from "./tool-registration.js";
+import { isParkRequest, PARK, PARKED_HISTORY, WAKE } from "../shared/parking.js";
+/** The agent runtime answers for its exited parked child from the captured native session. */
+function parkedHistory(pi, peer) {
+    let history;
+    pi.events.emit(PARKED_HISTORY, {
+        peer,
+        reply: (found) => {
+            history = found;
+        },
+    });
+    return history ?? Promise.reject(new Error("No agent runtime owns parked history."));
+}
 export default function piIntercomExtension(pi) {
     const config = loadConfig();
     const lifecycle = new IntercomLifecycle(pi, config, readIntercomLineage());
@@ -21,6 +33,7 @@ export default function piIntercomExtension(pi) {
     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);
@@ -29,13 +42,19 @@ export default function piIntercomExtension(pi) {
         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 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,
@@ -52,4 +71,26 @@ export default function piIntercomExtension(pi) {
         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/dist/pi-intercom/last-message.js

@@ -1,17 +1,6 @@
-function validPage(offset, limit) {
-    return (Number.isSafeInteger(offset) &&
-        offset >= 0 &&
-        Number.isSafeInteger(limit) &&
-        limit >= 1 &&
-        limit <= 16384);
-}
+import { isLastMessageQuery, LAST_MESSAGE_PAGE_LIMIT, } from "./types.js";
 function completedResponse(manager, entryId) {
-    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" &&
             (entry.message.stopReason === "stop" || entry.message.stopReason === "length") &&
@@ -24,15 +13,14 @@ function completedResponse(manager, entryId) {
                     .join("\n"),
             };
         }
-        id = entry.parentId;
     }
     return;
 }
 /** Reads finalized native history only; no model invocation or synthesized response. */
 export function readLastMessage(manager, session, query) {
     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.",
         };