@nicknisi/pi-relay 0.2.0 → 0.3.1

package/dist/index.js

@@ -18,7 +18,7 @@ import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { Box, getKeybindings, Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
 import { formatAudit, formatDelivery, formatListing, formatPendingAsk, refusalAmbiguous, refusalUnknown, shortAddr, } from './format.js';
-import { appendAudit, awaitReceipt, clearAsk, drain, deposit, pendingAsks, previewBody, readAudit, readOutgoingAsk, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
+import { ackClaimedLetter, appendAudit, awaitReceipt, claimInbox, clearAsk, deposit, outgoingAskIds, pendingAsks, previewBody, readAudit, readClaimedLetter, readOutgoingAsk, recoverInboxClaims, requeueClaimedLetter, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
 import { OutboundPolicy, inboundAccepts } from './policy.js';
 import { claimAlias, deriveAddr, ensureRoot, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeRecord, } from './registry.js';
 function toolResult(text, details = {}) {
@@ -99,10 +99,23 @@ export default function relay(pi) {
     let unwatch;
     let heartbeat;
     const askWaiters = new Map();
-    // Backoff while the session can't accept mail: a re-deposited letter
+    // Backoff while the session can't accept mail: a requeued letter
     // re-fires the watcher, and without this a failing sendMessage would spin
-    // drain→fail→re-deposit at watch speed.
+    // claim→fail→requeue at watch speed.
     let lastDeliveryFailureAt = 0;
+    // Letter ids this session has already accepted. Claims make redelivery
+    // possible (a crash between delivery and ack, or an ack failure after a
+    // successful send); without dedupe the model would see the body twice.
+    // Seeded from the transcript on session_start so recovery after a crash
+    // doesn't redeliver what the previous process already handed to the agent.
+    const deliveredIds = new Set();
+    const DELIVERED_IDS_CAP = 512;
+    const noteDelivered = (id) => {
+        deliveredIds.delete(id); // refresh recency
+        deliveredIds.add(id);
+        if (deliveredIds.size > DELIVERED_IDS_CAP)
+            deliveredIds.delete(deliveredIds.values().next().value);
+    };
     // Presence watch: addr → last observed presence. A poller surfaces
     // transitions as a notification message (no full turn wake).
     const watched = new Map();
@@ -122,7 +135,13 @@ export default function relay(pi) {
     function deliver(letter) {
         // Audited after the delivery attempts below: a 'deliver' record means the
         // session actually accepted the letter; refusal records 'deliver-failed'
-        // (the caller re-deposits, so logging here would duplicate every retry).
+        // (the caller requeues, so logging here would duplicate every retry).
+        // Note pi.sendMessage is fire-and-forget: asynchronous failures are
+        // swallowed by the runtime (emitted as extension errors, never rethrown),
+        // so only synchronous refusals — a disposed/uninitialized runtime during
+        // reload or shutdown — reach these catches. That is exactly the case
+        // where the letter never enters the transcript: async rejections from the
+        // triggerTurn path happen after the message is already in context.
         const auditDelivery = (event) => appendAudit(root, {
             ts: Date.now(),
             event,
@@ -186,7 +205,7 @@ export default function relay(pi) {
                 }
                 catch {
                     // session is shutting down or otherwise undeliverable — the caller
-                    // re-deposits the letter so a future drain retries
+                    // requeues the letter so a future drain retries
                     auditDelivery('deliver-failed');
                     return false;
                 }
@@ -196,40 +215,86 @@ export default function relay(pi) {
     function checkInbox() {
         if (!self)
             return;
+        const me = self.addr;
         if (Date.now() - lastDeliveryFailureAt < 5000)
             return;
-        // Refuse mode: never drain. Letters stay on disk (receipts honestly read
+        // Refuse mode: never claim. Letters stay on disk (receipts honestly read
         // 'queued') instead of being silently consumed and dropped.
         if (!inboundAccepts())
             return;
-        let letters;
+        // Claim, not drain: the inbox is detached atomically and each letter is
+        // only acked (deleted) once the session has accepted it. A claimed but
+        // unacked letter still reads 'queued' to the sender's receipt, survives
+        // a crash (recoverInboxClaims on the next session_start), and can be
+        // requeued for retry — unlink-as-read could silently lose it while the
+        // sender's receipt reported "delivered".
+        let claim;
         try {
-            letters = drain(root, self.addr);
+            claim = claimInbox(root, me);
         }
         catch {
             return;
         }
-        for (const letter of letters) {
+        if (!claim)
+            return;
+        const { claimToken, fileTokens } = claim;
+        const ack = (fileToken) => {
+            try {
+                ackClaimedLetter(root, me, claimToken, fileToken);
+            }
+            catch {
+                // ack failure leaves the letter claimed; recovery requeues it and
+                // deliveredIds suppresses the duplicate
+            }
+        };
+        for (const fileToken of fileTokens) {
+            let letter = null;
+            try {
+                letter = readClaimedLetter(root, me, claimToken, fileToken);
+            }
+            catch {
+                // transient read failure — keep it claimed rather than discarding
+                continue;
+            }
+            if (!letter || deliveredIds.has(letter.id)) {
+                // corrupt letters are discarded like drain does; already-accepted
+                // letters are redeliveries (crash between delivery and ack)
+                ack(fileToken);
+                continue;
+            }
             let accepted = false;
             try {
                 accepted = deliver(letter);
             }
             catch {
-                // a malformed delivery never blocks the rest of the drain
+                // a malformed delivery never blocks the rest of the claim
             }
-            if (!accepted) {
+            if (accepted) {
+                noteDelivered(letter.id);
+                ack(fileToken);
+            }
+            else {
                 lastDeliveryFailureAt = Date.now();
-                // Not handed to the session — put the letter back so a future drain
-                // retries it; otherwise drain's unlink-as-read would silently lose it
-                // while the sender's receipt reported "delivered".
+                // Not handed to the session — atomically return it to the live inbox
+                // so the watch/poll retries it.
                 try {
-                    deposit(root, self.addr, letter);
+                    requeueClaimedLetter(root, me, claimToken, fileToken);
                 }
                 catch {
-                    // inbox dir unwritable; nothing more we can do
+                    // stays claimed; the next session_start recovers it
                 }
             }
         }
+        // claimInbox renamed the watched inbox dir away and created a fresh one,
+        // so the fs.watch is now on a detached directory. Re-arm on the live
+        // inbox (the 3s poll covers anything deposited in between).
+        try {
+            unwatch?.();
+            unwatch = watchInbox(root, me, checkInbox);
+        }
+        catch {
+            // watch failure is non-fatal; the old poll timer died with the old watch
+        }
     }
     function myFrom() {
         const s = self;
@@ -363,6 +428,29 @@ export default function relay(pi) {
             writeRecord(root, self);
             const resumable = collectResumableSessionIds();
             sweep(root, Date.now(), (id) => resumable.has(id));
+            // Seed redelivery dedupe from the transcript: a letter delivered by a
+            // previous process but never acked (crash between delivery and ack)
+            // will be recovered below and must not be handed to the model twice.
+            for (const entry of ctx.sessionManager.getEntries()) {
+                if (entry.type !== 'custom_message' || entry.customType !== DELIVERY_TYPE)
+                    continue;
+                const id = entry.details?.id;
+                if (typeof id === 'string')
+                    noteDelivered(id);
+            }
+            // Recover letters stranded in durable claims by a crash mid-delivery:
+            // return them to the live inbox so the normal watch/poll retries them.
+            // Runs before the watch is armed so requeues land in the watched inbox.
+            for (const stranded of recoverInboxClaims(root, self.addr)) {
+                for (const fileToken of stranded.fileTokens) {
+                    try {
+                        requeueClaimedLetter(root, self.addr, stranded.claimToken, fileToken);
+                    }
+                    catch {
+                        // stays claimed; the next session_start retries recovery
+                    }
+                }
+            }
             unwatch?.();
             unwatch = watchInbox(root, self.addr, checkInbox);
             heartbeat = setInterval(() => writeSelf({}), 15_000);
@@ -690,16 +778,7 @@ export default function relay(pi) {
 }
 /** Find an outgoing ask id by exact id or unique prefix (for cancel ergonomics). */
 function resolveOutAskId(root, addr, idOrPrefix) {
-    let names;
-    try {
-        names = fs.readdirSync(path.join(root, `${addr}.asks`));
-    }
-    catch {
-        return undefined;
-    }
-    const ids = names
-        .filter((f) => f.startsWith('out-') && f.endsWith('.json'))
-        .map((f) => f.slice('out-'.length, -'.json'.length));
+    const ids = outgoingAskIds(root, addr);
     if (ids.includes(idOrPrefix))
         return idOrPrefix;
     const matches = ids.filter((id) => id.startsWith(idOrPrefix));

package/dist/mailbox.d.ts

@@ -4,11 +4,13 @@
  * Guarantees (each pinned by a test):
  * - A reader never sees half a letter: writers rename into place; readers
  *   only look at `*.json`.
- * - Nothing is delivered twice: a letter is unlinked as it is read, BEFORE
- *   the caller handles it.
+ * - A letter is deleted only once consumed: drain unlinks as it reads, and
+ *   the durable claim flow deletes only on explicit ack — a crashed or
+ *   failed delivery leaves the letter recoverable (recoverInboxClaims) or
+ *   requeueable.
  * - A corrupt letter is discarded on read, so it cannot poison every drain.
  * - Consumption is the receipt: the sender learns "delivered" only when the
- *   letter actually disappeared from the target's inbox.
+ *   letter actually disappeared from the target's inbox and durable claims.
  * - Every deposit and every delivery appends one append-only audit line —
  *   drain-as-receipt must not destroy evidence. The log never holds a full
  *   body, only a short preview.
@@ -27,13 +29,17 @@ export interface Letter {
     ts: number;
 }
 export declare const MAX_BODY_CHARS: number;
-/** Atomic deposit: write to a tmp sibling, then rename into place. */
+/** Atomic deposit: write to a random exclusive tmp sibling, then rename into place. */
 export declare function deposit(root: string, toAddr: string, letter: Letter): void;
 /**
  * Take every letter in the inbox, oldest first. Each letter is unlinked as
  * it is read — before parsing — so it can never be delivered twice. The
- * tradeoff: a drained letter that is never delivered would be lost, so the
- * caller must re-deposit any letter it fails to deliver (checkInbox does).
+ * tradeoff: a drained letter that is never delivered is lost, so callers
+ * that can fail delivery should prefer the durable claim flow (claimInbox →
+ * readClaimedLetter → ackClaimedLetter/requeueClaimedLetter), which only
+ * deletes a letter once it has actually been handed off. The pi entry point
+ * (index.ts checkInbox) uses claims; drain remains for core consumers that
+ * handle drained letters synchronously.
  */
 export declare function drain(root: string, addr: string): Letter[];
 export declare function unreadCount(root: string, addr: string): number;
@@ -44,10 +50,24 @@ export declare function unreadCount(root: string, addr: string): number;
  * a process alive.
  */
 export declare function watchInbox(root: string, addr: string, onMail: () => void): () => void;
+export interface InboxClaim {
+    claimToken: string;
+    fileTokens: string[];
+}
+/** Atomically detach the current non-empty inbox and return its durable tokens. */
+export declare function claimInbox(root: string, addr: string): InboxClaim | null;
+/** Enumerate durable claims left by this or a crashed consumer. */
+export declare function recoverInboxClaims(root: string, addr: string): InboxClaim[];
+/** Read and validate one claimed letter without exposing or following a path. */
+export declare function readClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): Letter | null;
+/** Permanently acknowledge/delete one claimed letter. Idempotent. */
+export declare function ackClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean;
+/** Atomically return one claimed letter to the current inbox. */
+export declare function requeueClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean;
 /**
  * Consumption receipt: after depositing to a LIVE target, wait briefly for
- * the letter to vanish. 'delivered' means the receiver's drainer took it —
- * stronger than any transport ack.
+ * the exact letter to vanish from both the live inbox and durable claims.
+ * 'delivered' means the receiver acknowledged it, not merely claimed it.
  */
 export declare function awaitReceipt(root: string, toAddr: string, letter: Letter, timeoutMs?: number): Promise<'delivered' | 'queued'>;
 export interface OutAsk {
@@ -82,3 +102,5 @@ export declare function readAudit(root: string, limit?: number): AuditRecord[];
 export declare function resolveAskByRef(root: string, addr: string, replyTo: string): Letter | null;
 /** Asks we have received and not yet answered, oldest first. */
 export declare function pendingAsks(root: string, addr: string): Letter[];
+/** Outgoing ask ids, used by the Pi entry point for prefix resolution. */
+export declare function outgoingAskIds(root: string, addr: string): string[];