evolcore 0.0.18 → 0.0.20

package/dist/aun/outbox.js

@@ -3,6 +3,7 @@ import { agentOutboxPath } from '../paths.js';
 import { atomicRead, atomicWrite } from '../utils/atomic-write.js';
 import { isDeliveryTarget, isDeliveryTargetForChannel, sameDeliveryTarget } from '../core/message/message-utils.js';
 const MAX_ENTRIES_PER_AID = 20;
+const MAX_TERMINAL_ENTRIES_PER_AID = 100;
 const DEFAULT_TTL = 300_000; // 5 minutes
 function outboxFile(aid) {
     return agentOutboxPath(aid);
@@ -13,6 +14,11 @@ function generateId() {
     return `out-${ts}-${rand}`;
 }
 function isExpired(entry) {
+    // Terminal failures are retained as durable diagnostics. They are excluded
+    // from `load()`/`hasPending()` and must not disappear merely because the
+    // original delivery TTL elapsed.
+    if (entry.terminal)
+        return false;
     if (entry.critical)
         return false;
     return Date.now() - entry.ts > entry.ttl;
@@ -41,11 +47,22 @@ function readEntries(aid) {
 }
 function writeEntries(aid, entries) {
     const file = outboxFile(aid);
-    const content = entries.length > 0
-        ? entries.map(e => JSON.stringify(e)).join('\n') + '\n'
+    const boundedEntries = trimTerminalEntries(entries);
+    const content = boundedEntries.length > 0
+        ? boundedEntries.map(e => JSON.stringify(e)).join('\n') + '\n'
         : '';
     atomicWrite(file, content);
 }
+function trimTerminalEntries(entries) {
+    const terminalEntries = entries.filter(entry => !!entry.terminal);
+    if (terminalEntries.length <= MAX_TERMINAL_ENTRIES_PER_AID)
+        return entries;
+    const retainedTerminalIds = new Set(terminalEntries
+        .sort((left, right) => (left.terminal?.at ?? left.ts) - (right.terminal?.at ?? right.ts))
+        .slice(-MAX_TERMINAL_ENTRIES_PER_AID)
+        .map(entry => entry.id));
+    return entries.filter(entry => !entry.terminal || retainedTerminalIds.has(entry.id));
+}
 export function enqueue(aid, opts) {
     const delivery = opts.delivery;
     if (!isDeliveryForChannel(delivery, opts.channelId)) {
@@ -54,6 +71,9 @@ export function enqueue(aid, opts) {
     }
     let existingEntries = readEntries(aid);
     if (opts.dedupeKey) {
+        // Terminal results are decisions for this logical operation. Reusing the
+        // same route must not silently turn a permanent rejection into a retry;
+        // an explicit route correction is the only case that replaces it.
         const existing = existingEntries.find(entry => entry.dedupeKey === opts.dedupeKey && !isExpired(entry));
         if (existing
             && existing.channelId === opts.channelId
@@ -86,10 +106,12 @@ export function enqueue(aid, opts) {
         ttl: opts.ttl ?? DEFAULT_TTL,
         postSend: opts.postSend,
     };
-    // Enforce cap: read existing, drop oldest if over limit
+    // Enforce the pending-entry cap without allowing historical terminal
+    // diagnostics to evict live messages. Terminal records are bounded
+    // separately so a permanently failing target cannot grow the file forever.
     let entries = existingEntries;
-    if (entries.filter(candidate => !candidate.critical).length >= MAX_ENTRIES_PER_AID) {
-        const dropIndex = entries.findIndex(candidate => !candidate.critical);
+    if (entries.filter(candidate => !candidate.critical && !candidate.terminal).length >= MAX_ENTRIES_PER_AID) {
+        const dropIndex = entries.findIndex(candidate => !candidate.critical && !candidate.terminal);
         if (dropIndex >= 0)
             entries.splice(dropIndex, 1);
         entries = [...entries, entry];
@@ -104,6 +126,16 @@ export function remove(aid, id) {
     const entries = readEntries(aid).filter(e => e.id !== id);
     writeEntries(aid, entries);
 }
+/** Remove an entry only if it still points at the route that was submitted. */
+export function removeIfRouteMatches(aid, submitted) {
+    const entries = readEntries(aid);
+    const index = entries.findIndex(entry => entry.id === submitted.id);
+    if (index < 0 || !hasSamePersistedRoute(entries[index], submitted))
+        return false;
+    entries.splice(index, 1);
+    writeEntries(aid, entries);
+    return true;
+}
 /** Replace an existing entry without consuming another outbox slot. */
 export function replace(aid, entry) {
     const entries = readEntries(aid);
@@ -114,6 +146,30 @@ export function replace(aid, entry) {
     writeEntries(aid, entries);
     return true;
 }
+/** Replace an entry only while its submitted route is still current. */
+export function replaceIfRouteMatches(aid, submitted, replacement) {
+    const entries = readEntries(aid);
+    const index = entries.findIndex(candidate => candidate.id === submitted.id);
+    if (index < 0)
+        return 'missing';
+    if (!hasSamePersistedRoute(entries[index], submitted))
+        return 'route-changed';
+    entries[index] = replacement;
+    writeEntries(aid, entries);
+    return 'replaced';
+}
+/** Update only the delivery receipt while preserving concurrent entry changes. */
+export function updateDeliveryReceiptIfRouteMatches(aid, submitted, receipt) {
+    const entries = readEntries(aid);
+    const index = entries.findIndex(candidate => candidate.id === submitted.id);
+    if (index < 0)
+        return 'missing';
+    if (!hasSamePersistedRoute(entries[index], submitted))
+        return 'route-changed';
+    entries[index].deliveryReceipt = receipt;
+    writeEntries(aid, entries);
+    return 'replaced';
+}
 /** Remove durable interaction cards that were cancelled before delivery. */
 export function removeInteractionCards(aid, requestId) {
     const entries = readEntries(aid);
@@ -125,10 +181,13 @@ export function removeInteractionCards(aid, requestId) {
     return removed;
 }
 export function load(aid) {
-    return readEntries(aid).filter(e => !isExpired(e));
+    return readEntries(aid).filter(e => !e.terminal && !isExpired(e));
 }
-export function findByDedupeKey(aid, dedupeKey) {
-    return load(aid).find(entry => entry.dedupeKey === dedupeKey);
+export function findByDedupeKey(aid, dedupeKey, opts = {}) {
+    const entries = opts.includeTerminal
+        ? readEntries(aid).filter(entry => !isExpired(entry))
+        : load(aid);
+    return entries.find(entry => entry.dedupeKey === dedupeKey);
 }
 export function cleanup(aid) {
     const all = readEntries(aid);
@@ -138,6 +197,19 @@ export function cleanup(aid) {
         writeEntries(aid, valid);
     return removed;
 }
+/** Mark a durable entry terminal while keeping its reason for diagnostics. */
+export function markTerminal(aid, id, failure, submitted) {
+    const entries = readEntries(aid);
+    const entry = entries.find(candidate => candidate.id === id);
+    if (!entry || (submitted && !hasSamePersistedRoute(entry, submitted)))
+        return false;
+    entry.lastError = failure.error ?? 'permanent send failure';
+    if (failure.code !== undefined)
+        entry.lastErrorCode = failure.code;
+    entry.terminal = { at: Date.now(), error: entry.lastError, ...(failure.code !== undefined ? { code: failure.code } : {}) };
+    writeEntries(aid, entries);
+    return true;
+}
 // Each caller gets its own pass over the current disk state. This prevents
 // duplicate sends while allowing a later drain trigger to pick up entries
 // enqueued during an active pass.
@@ -145,14 +217,25 @@ const activeDrainTails = new Map();
 function hasRouteForChannel(entry) {
     return isDeliveryForChannel(entry.delivery, entry.channelId);
 }
+function hasSamePersistedRoute(left, right) {
+    if (left.channelId !== right.channelId)
+        return false;
+    if (left.delivery === undefined && right.delivery === undefined)
+        return true;
+    return isDeliveryTarget(left.delivery)
+        && isDeliveryTarget(right.delivery)
+        && sameDeliveryTarget(left.delivery, right.delivery);
+}
 async function drainOnce(aid, sender) {
-    const entries = readEntries(aid);
+    const entries = readEntries(aid).filter(entry => !entry.terminal);
     if (entries.length === 0)
         return { sent: 0, expired: 0, failed: 0 };
     const drainedIds = new Set(entries.map(e => e.id));
+    const drainedById = new Map(entries.map(entry => [entry.id, entry]));
     let sent = 0;
     let expired = 0;
     let failed = 0;
+    let permanent = 0;
     const remaining = [];
     for (const entry of entries) {
         if (isExpired(entry)) {
@@ -161,20 +244,48 @@ async function drainOnce(aid, sender) {
         }
         if (!hasRouteForChannel(entry)) {
             // A route is security-sensitive metadata. An entry whose groupId does
-            // not match its address cannot be repaired from channelId, so remove it
-            // instead of retrying the same malformed send forever.
-            expired++;
+            // not match its address cannot be repaired from channelId. Keep a
+            // terminal diagnostic record instead of retrying the same malformed
+            // send forever or silently deleting evidence of the failure.
+            permanent++;
+            entry.lastError = 'outbox entry has no valid delivery route';
+            entry.lastErrorCode = 'AUN_OUTBOUND_ROUTE_REQUIRED';
+            entry.terminal = {
+                at: Date.now(),
+                error: entry.lastError,
+                code: entry.lastErrorCode,
+            };
+            remaining.push(entry);
             continue;
         }
         try {
             entry.attempts = (entry.attempts ?? 0) + 1;
-            const ok = await sender(entry);
-            if (ok) {
+            const raw = await sender(entry);
+            const result = typeof raw === 'boolean'
+                ? { status: raw ? 'sent' : 'retry' }
+                : raw;
+            if (result.status === 'sent') {
                 sent++;
             }
+            else if (result.status === 'permanent') {
+                permanent++;
+                entry.lastError = result.error ?? 'permanent send failure';
+                if (result.code !== undefined)
+                    entry.lastErrorCode = result.code;
+                entry.terminal = {
+                    at: Date.now(),
+                    error: entry.lastError,
+                    ...(result.code !== undefined ? { code: result.code } : {}),
+                };
+                // Keep a terminal record for diagnostics, but exclude it from all
+                // pending-send views so the timer cannot submit it again.
+                remaining.push(entry);
+            }
             else {
                 failed++;
-                entry.lastError = 'sender returned false';
+                entry.lastError = result.error ?? 'sender returned false';
+                if (result.code !== undefined)
+                    entry.lastErrorCode = result.code;
                 remaining.push(entry);
             }
         }
@@ -190,17 +301,31 @@ async function drainOnce(aid, sender) {
         if (!drainedIds.has(entry.id))
             return [entry];
         const failedEntry = failedById.get(entry.id);
-        if (!failedEntry)
-            return [];
+        if (!failedEntry) {
+            const submittedEntry = drainedById.get(entry.id);
+            return submittedEntry && !hasSamePersistedRoute(entry, submittedEntry)
+                ? [entry]
+                : [];
+        }
+        // A failure belongs to the route that was actually submitted. If another
+        // writer corrected that route while the RPC was in flight, preserve the
+        // corrected entry as pending instead of terminating it with a stale
+        // target's permanent error.
+        if (!hasSamePersistedRoute(entry, failedEntry))
+            return [entry];
+        if (entry.terminal && !failedEntry.terminal)
+            return [entry];
         return [{
                 ...failedEntry,
                 ...entry,
                 attempts: failedEntry.attempts,
                 lastError: failedEntry.lastError,
+                lastErrorCode: failedEntry.lastErrorCode,
+                ...(failedEntry.terminal ? { terminal: failedEntry.terminal } : {}),
             }];
     });
     writeEntries(aid, retained);
-    return { sent, expired, failed };
+    return { sent, expired, failed, ...(permanent > 0 ? { permanent } : {}) };
 }
 export async function drain(aid, sender) {
     const previous = activeDrainTails.get(aid);
@@ -220,7 +345,7 @@ export async function drain(aid, sender) {
     }
 }
 export function hasPending(aid) {
-    return readEntries(aid).some(entry => !isExpired(entry));
+    return readEntries(aid).some(entry => !entry.terminal && !isExpired(entry));
 }
 /**
  * 当前 outbox 中待发送条目数。用于诊断发送管线堵塞：depth 持续增长说明