@sema-agent/core 7.56.0 → 7.57.0

package/dist/agents/peer-held-queue.js

@@ -1,3 +1,4 @@
+import { isMailboxDecisionDeliverable, isMailboxDecisionFinal } from "../core/mailbox-store.js";
 import { PEER_HELD_QUEUE_CAP, PEER_HELD_REVIEW_CAUSES } from "./peer-notices.js";
 import { peerSessionBoxHandle } from "./peer-directory.js";
 export const realPeerClock = {
@@ -10,14 +11,23 @@ export const realPeerClock = {
     clearTimeout: (h) => clearTimeout(h),
 };
 const crashHandlers = new WeakMap();
-export const PEER_HELD_DECISION_MEMORY = PEER_HELD_QUEUE_CAP * 4;
 export function createPeerHeldQueue(key, opts = {}) {
     const cap = opts.cap ?? PEER_HELD_QUEUE_CAP;
     const clock = opts.clock ?? realPeerClock;
     const entries = [];
     const deadlines = new Map();
-    const decisions = new Map();
     let cfg;
+    const cardChains = new Map();
+    const onCard = (seq, f) => {
+        const run = (cardChains.get(seq) ?? Promise.resolve()).then(f);
+        const tail = run.then(() => undefined, () => undefined);
+        cardChains.set(seq, tail);
+        void tail.then(() => {
+            if (cardChains.get(seq) === tail)
+                cardChains.delete(seq);
+        });
+        return run;
+    };
     const sinkOrThrow = () => {
         if (cfg === undefined)
             throw new Error("PeerHeldQueue: not configured — bind a run (configure) before holding messages");
@@ -43,103 +53,199 @@ export function createPeerHeldQueue(key, opts = {}) {
             entries.splice(i, 1);
         clearDeadline(entry.seq);
     };
-    const settleOut = (entry, settlement, reason, receipt) => {
+    const leave = (entry, settlement, reason, receipt) => {
         const sink = sinkOrThrow();
         remove(entry);
-        if (settlement !== "delivered") {
-            decisions.set(entry.seq, settlement);
-            while (decisions.size > PEER_HELD_DECISION_MEMORY) {
-                const oldest = decisions.keys().next();
-                if (oldest.done === true)
-                    break;
-                decisions.delete(oldest.value);
-            }
-        }
         if (receipt !== undefined)
             safe(() => sink.receipt(entry, receipt));
         safe(() => sink.onSettled?.(entry, settlement, reason, entries.length));
     };
+    const move = async (entry, next) => {
+        const sink = sinkOrThrow();
+        let outcome;
+        try {
+            outcome = await sink.decide(entry, entry.decision, next);
+        }
+        catch (e) {
+            safe(() => sink.onFault?.(entry, e));
+            return "fault";
+        }
+        if (outcome.ok)
+            return "won";
+        adoptCurrent(entry, outcome.current);
+        return "lost";
+    };
+    const adoptCurrent = (entry, current) => {
+        if (!entries.includes(entry))
+            return;
+        if (current === "gone" || current === "unset")
+            return leave(entry, "retired", "superseded", undefined);
+        if (isMailboxDecisionFinal(current))
+            return leave(entry, current, "decided_elsewhere", undefined);
+        if (isMailboxDecisionDeliverable(current) && entry.decision !== current) {
+            entry.decision = current;
+            clearDeadline(entry.seq);
+        }
+    };
+    const settleLocal = async (entry, settlement, reason) => {
+        const sink = sinkOrThrow();
+        let tells = false;
+        try {
+            tells = sink.tellsSender(entry);
+        }
+        catch {
+            tells = false;
+        }
+        const from = settlement === "expired" ? "held" : "delivered";
+        if (!tells || entry.decision !== from)
+            return leave(entry, "retired", reason, undefined);
+        const r = await move(entry, settlement);
+        if (r === "won")
+            leave(entry, settlement, reason, settlement);
+        else if (r === "fault")
+            leave(entry, "retired", reason, undefined);
+    };
     const armDeadline = (entry) => {
         if (cfg === undefined || cfg.dialogExpiryMs === null || deadlines.has(entry.seq))
             return;
-        if (entry.released === true)
+        if (entry.decision !== "held")
             return;
         if (!PEER_HELD_REVIEW_CAUSES.includes(entry.cause))
             return;
         const h = clock.setTimeout(() => {
             deadlines.delete(entry.seq);
-            if (!entries.includes(entry))
-                return;
-            rejudge();
-            if (!entries.includes(entry))
-                return;
-            settleOut(entry, "expired", "deadline", "expired");
+            void (async () => {
+                if (!entries.includes(entry))
+                    return;
+                await rejudge();
+                await onCard(entry.seq, async () => {
+                    if (!entries.includes(entry) || entry.decision !== "held")
+                        return;
+                    if ((await move(entry, "expired")) === "won")
+                        leave(entry, "expired", "deadline", "expired");
+                });
+            })().catch(() => undefined);
         }, cfg.dialogExpiryMs);
         deadlines.set(entry.seq, h);
     };
-    const tryDeliver = (entry, reason) => {
+    const mayHandOver = (entry) => {
         const sink = sinkOrThrow();
         if (sink.inject === undefined)
+            return false;
+        try {
+            return sink.canInject === undefined || sink.canInject(entry);
+        }
+        catch {
+            return false;
+        }
+    };
+    const tryDeliver = async (entry, reason) => {
+        const sink = sinkOrThrow();
+        if (sink.inject === undefined || !mayHandOver(entry))
             return "no_leg";
+        if (entry.decision !== "delivered") {
+            const r = await move(entry, "delivered");
+            if (r === "lost")
+                return "lost";
+            if (r === "fault")
+                return "no_leg";
+            entry.decision = "delivered";
+            clearDeadline(entry.seq);
+        }
         try {
             if (sink.inject(entry) === "deferred")
                 return "no_leg";
         }
         catch {
-            settleOut(entry, "dropped", "inject_failed", "dropped");
+            await settleLocal(entry, "dropped", "inject_failed");
             return "dropped";
         }
-        settleOut(entry, "delivered", reason, "delivered");
+        leave(entry, "delivered", reason, "delivered");
         return "delivered";
     };
-    const reconcile = (present) => {
+    const refuseCard = async (entry, reason) => {
+        const owed = entry.decision === "delivered";
+        if (owed && !mayHandOver(entry))
+            return "waits";
+        const word = owed ? "dropped" : "refused";
+        const r = await move(entry, word);
+        if (r === "won")
+            leave(entry, word, reason, word);
+        return r;
+    };
+    const rejudgeOne = async (entry, reannounce) => {
+        const sink = sinkOrThrow();
+        let verdict;
+        try {
+            verdict = sink.judge(entry);
+        }
+        catch {
+            return "held";
+        }
+        if (verdict.verdict === "refuse")
+            return (await refuseCard(entry, "rejudge")) === "won" ? "refused" : "held";
+        if (verdict.verdict === "deliver" || isMailboxDecisionDeliverable(entry.decision)) {
+            const r = await tryDeliver(entry, entry.decision === "approved" ? "approved" : "rejudge");
+            return r === "delivered" ? "released" : "held";
+        }
+        if (verdict.verdict === "hold" && verdict.cause !== entry.cause) {
+            entry.cause = verdict.cause;
+            reannounce.push([entry, verdict.cause]);
+            clearDeadline(entry.seq);
+            armDeadline(entry);
+        }
+        return "held";
+    };
+    const rejudge = async () => {
+        sinkOrThrow();
+        let released = 0;
+        let refused = 0;
+        const reannounce = [];
+        for (const entry of [...entries]) {
+            const r = await onCard(entry.seq, async () => (entries.includes(entry) ? rejudgeOne(entry, reannounce) : "held"));
+            if (r === "released")
+                released += 1;
+            else if (r === "refused")
+                refused += 1;
+        }
         const sink = sinkOrThrow();
+        for (const [entry, cause] of reannounce)
+            if (entries.includes(entry))
+                safe(() => sink.onHeld?.(entry, entries.length, cause, true));
+        return { released, refused, held: entries.length };
+    };
+    const reconcile = (snapshot) => {
+        sinkOrThrow();
         let retired = 0;
         for (const entry of [...entries]) {
-            if (present.has(entry.seq))
+            if (cardChains.has(entry.seq))
                 continue;
-            remove(entry);
-            retired += 1;
-            safe(() => sink.onSettled?.(entry, "expired", "superseded", entries.length));
+            const present = snapshot.has(entry.seq);
+            const before = entries.length;
+            adoptCurrent(entry, present ? (snapshot.get(entry.seq) ?? "unset") : "gone");
+            if (entries.length < before)
+                retired += 1;
         }
         return retired;
     };
-    const rejudge = () => {
+    const makeRoom = async () => {
+        if (entries.length < cap)
+            return true;
         const sink = sinkOrThrow();
-        let released = 0;
-        let refused = 0;
-        const reannounce = [];
-        for (const entry of [...entries]) {
-            let verdict;
+        const victim = entries.find((e) => {
+            if (e.decision !== "held")
+                return false;
             try {
-                verdict = sink.judge(entry);
+                return sink.tellsSender(e);
             }
             catch {
-                continue;
+                return false;
             }
-            if (verdict.verdict === "refuse") {
-                settleOut(entry, "refused", "rejudge", "refused");
-                refused += 1;
-                continue;
-            }
-            if (verdict.verdict === "deliver" || entry.released === true) {
-                const r = tryDeliver(entry, entry.released === true ? "approved" : "rejudge");
-                if (r === "no_leg")
-                    entry.released = true;
-                else if (r === "delivered")
-                    released += 1;
-                continue;
-            }
-            if (verdict.cause !== entry.cause) {
-                entry.cause = verdict.cause;
-                reannounce.push([entry, verdict.cause]);
-                clearDeadline(entry.seq);
-                armDeadline(entry);
-            }
-        }
-        for (const [entry, cause] of reannounce)
-            safe(() => sink.onHeld?.(entry, entries.length, cause, true));
-        return { released, refused, held: entries.length };
+        });
+        if (victim === undefined)
+            return false;
+        await onCard(victim.seq, async () => (entries.includes(victim) ? settleLocal(victim, "expired", "evicted") : undefined));
+        return entries.length < cap;
     };
     const queue = {
         key,
@@ -160,63 +266,55 @@ export function createPeerHeldQueue(key, opts = {}) {
             cfg = { ...cfg, sink: rest };
         },
         configured: () => cfg !== undefined,
-        hold(input) {
+        async hold(input, known) {
             const sink = sinkOrThrow();
             if (entries.some((e) => e.box === input.box && e.seq === input.seq))
-                return;
-            const entry = { ...input, heldAt: clock.now() };
-            if (entries.length >= cap) {
-                const oldest = entries[0];
-                settleOut(oldest, "expired", "evicted", "expired");
+                return "adopted";
+            let state = known ?? "held";
+            let fresh = false;
+            if (known === undefined) {
+                let outcome;
+                try {
+                    outcome = await sink.decide({ ...input, heldAt: clock.now(), decision: "held" }, undefined, "held");
+                }
+                catch (e) {
+                    safe(() => sink.onFault?.({ ...input, heldAt: clock.now(), decision: "held" }, e));
+                    return "fault";
+                }
+                if (outcome.ok)
+                    fresh = true;
+                else if (outcome.current === "gone" || outcome.current === "unset")
+                    return "gone";
+                else if (isMailboxDecisionFinal(outcome.current))
+                    return outcome.current;
+                else
+                    state = outcome.current;
+            }
+            if (entries.some((e) => e.box === input.box && e.seq === input.seq))
+                return fresh ? "held" : "adopted";
+            if (!(await makeRoom())) {
+                if (fresh)
+                    safe(() => sink.receipt({ ...input, heldAt: clock.now(), decision: state }, "held"));
+                return "uncarded";
             }
+            const entry = { ...input, heldAt: clock.now(), decision: state };
             entries.push(entry);
             armDeadline(entry);
-            safe(() => sink.onHeld?.(entry, entries.length, entry.cause, false));
-            safe(() => sink.receipt(entry, "held"));
+            if (state === "held")
+                safe(() => sink.onHeld?.(entry, entries.length, entry.cause, false));
+            if (fresh)
+                safe(() => sink.receipt(entry, "held"));
+            return fresh ? "held" : "adopted";
         },
         rejudge,
         reconcile,
         settle(seq, decision) {
-            const sink = sinkOrThrow();
-            const entry = entries.find((e) => e.seq === seq);
-            if (entry === undefined)
-                return "gone";
-            if (decision === "deny") {
-                settleOut(entry, "denied", "denied", "denied");
-                return "denied";
-            }
-            if (decision === "cancel") {
-                settleOut(entry, "expired", "cancelled", "expired");
-                return "expired";
-            }
-            let verdict;
-            try {
-                verdict = sink.judge(entry);
-            }
-            catch {
-                entry.released = true;
-                return "released_pending";
-            }
-            if (verdict.verdict === "refuse") {
-                settleOut(entry, "refused", "approved", "refused");
-                return "dropped_by_policy";
-            }
-            const r = tryDeliver(entry, "approved");
-            if (r === "no_leg") {
-                entry.released = true;
-                clearDeadline(entry.seq);
-                return "released_pending";
-            }
-            return r;
+            return onCard(seq, () => settleCard(seq, decision));
         },
+        has: (seq) => entries.some((e) => e.seq === seq),
         list: () => entries.map((e) => ({ ...e, ...(e.hopChain !== undefined ? { hopChain: [...e.hopChain] } : {}), ...(e.peerMeta !== undefined ? { peerMeta: { ...e.peerMeta } } : {}) })),
         size: () => entries.length,
-        decisions: () => decisions,
-        forgetDecisions(seqs) {
-            for (const seq of seqs)
-                decisions.delete(seq);
-        },
-        shutdown() {
+        async shutdown() {
             if (cfg === undefined) {
                 entries.length = 0;
                 for (const h of deadlines.values())
@@ -224,12 +322,63 @@ export function createPeerHeldQueue(key, opts = {}) {
                 deadlines.clear();
                 return;
             }
-            for (const entry of [...entries])
-                settleOut(entry, "expired", "shutdown", "expired");
+            for (const entry of [...entries]) {
+                await onCard(entry.seq, async () => {
+                    if (entries.includes(entry))
+                        await settleLocal(entry, "expired", "shutdown");
+                });
+            }
         },
     };
+    async function settleCard(seq, decision) {
+        const sink = sinkOrThrow();
+        const entry = entries.find((e) => e.seq === seq);
+        if (entry === undefined)
+            return "gone";
+        const handedOver = entry.decision === "delivered";
+        if (decision === "deny" || decision === "cancel") {
+            if (handedOver)
+                return "delivered";
+            const word = decision === "deny" ? "denied" : "expired";
+            const r = await move(entry, word);
+            if (r === "fault")
+                throw new Error(`PeerHeldQueue.settle: the ${decision} of seq ${seq} could not be recorded (the store refused the move); nothing was decided`);
+            if (r === "lost")
+                return "decided_elsewhere";
+            leave(entry, word, decision === "deny" ? "denied" : "cancelled", word);
+            return word;
+        }
+        let verdict;
+        try {
+            verdict = sink.judge(entry);
+        }
+        catch {
+            verdict = undefined;
+        }
+        if (verdict?.verdict === "refuse") {
+            const r = await refuseCard(entry, "approved");
+            if (r === "fault")
+                throw new Error(`PeerHeldQueue.settle: the refusal of seq ${seq} could not be recorded (the store refused the move)`);
+            if (r !== "waits")
+                return r === "lost" ? "decided_elsewhere" : "dropped_by_policy";
+        }
+        if (handedOver)
+            return "delivered";
+        if (entry.decision === "held") {
+            const r = await move(entry, "approved");
+            if (r === "fault")
+                throw new Error(`PeerHeldQueue.settle: the approval of seq ${seq} could not be recorded (the store refused the move); nothing was decided`);
+            if (r === "lost")
+                return "decided_elsewhere";
+            entry.decision = "approved";
+            clearDeadline(entry.seq);
+        }
+        if (verdict === undefined)
+            return "released_pending";
+        const d = await tryDeliver(entry, "approved");
+        return d === "no_leg" ? "released_pending" : d === "lost" ? "decided_elsewhere" : d;
+    }
     crashHandlers.set(queue, () => {
-        decisions.clear();
         entries.length = 0;
         for (const h of deadlines.values())
             clock.clearTimeout(h);