evolcore 0.0.12 → 0.0.13

package/dist/core/message/message-queue.js

@@ -21,6 +21,9 @@ export class MessageQueue {
     interceptors = new Map();
     mutedAgents = new Set(); // 禁言的 agent：消息照常入队，但不取出给大模型
     persistencePath;
+    dedupPath;
+    dedupTtlMs;
+    durableMessageIds = new Map();
     activeBatches = new Map();
     processingStartTime = new Map(); // queueKey → 处理开始时间戳
     queueKeyToSessionKey = new Map(); // queueKey → sessionKey（human-readable 格式）
@@ -32,6 +35,10 @@ export class MessageQueue {
     constructor(handler, options) {
         this.handler = handler;
         this.persistencePath = options?.persistencePath;
+        this.dedupPath = options?.dedupPath
+            ?? (this.persistencePath ? `${this.persistencePath}.dedup.json` : undefined);
+        this.dedupTtlMs = Math.max(60_000, options?.dedupTtlMs ?? 7 * 24 * 60 * 60 * 1000);
+        this.restoreDurableDedup();
     }
     /** 暴露逻辑队列桥接，供响应模式系统注入队列工厂 */
     getLogicalQueueBridge() {
@@ -108,16 +115,22 @@ export class MessageQueue {
     /**
      * 检查消息是否应该处理（去重）
      *
-     * 去重 key = `${sessionKey}:${messageId}`，而非裸 messageId。
+     * 去重 key = `${selfAID}:${sessionKey}:${messageId}`，而非裸 messageId。
      * MessageQueue 是进程级单例，被所有 evolagent 共享。AUN 群广播时同一条群消息
      * 会投递给群里每个 evolagent，它们 messageId 相同但 session 不同，必须各处理一次。
-     * 裸 messageId 去重会让先入队的 agent 吞掉其他 agent 的消息。
+     * 裸 messageId 或仅按 session 去重都会让先入队的 agent 吞掉其他 agent 的消息。
      */
-    shouldProcess(sessionKey, message) {
+    dedupKey(sessionKey, messageId, selfAID) {
+        return `${selfAID ?? ''}:${sessionKey}:${messageId}`;
+    }
+    shouldProcess(sessionKey, message, selfAID) {
         if (!message.messageId)
             return true; // 无 ID 的消息不去重
-        const dedupKey = `${sessionKey}:${message.messageId}`;
-        if (this.recentMessageIds.has(dedupKey) || this.hasEnqueuedMessage(sessionKey, message.messageId)) {
+        const scope = selfAID ?? message.selfAID;
+        const dedupKey = this.dedupKey(sessionKey, message.messageId, scope);
+        if (this.recentMessageIds.has(dedupKey)
+            || this.durableMessageIds.has(dedupKey)
+            || this.hasEnqueuedMessage(sessionKey, message.messageId, scope)) {
             logger.debug(`[Queue] Duplicate message ${dedupKey}, skipping`);
             return false;
         }
@@ -125,17 +138,69 @@ export class MessageQueue {
         setTimeout(() => this.recentMessageIds.delete(dedupKey), this.DEDUP_WINDOW);
         return true;
     }
-    hasEnqueuedMessage(sessionKey, messageId) {
+    rememberDurably(sessionKey, message, selfAID) {
+        if (!this.dedupPath || !message.messageId)
+            return;
+        this.durableMessageIds.set(this.dedupKey(sessionKey, message.messageId, selfAID ?? message.selfAID), Date.now());
+        this.persistDurableDedup();
+    }
+    restoreDurableDedup() {
+        if (!this.dedupPath || !fs.existsSync(this.dedupPath))
+            return;
+        const now = Date.now();
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.dedupPath, 'utf8'));
+            const entries = Array.isArray(raw)
+                ? raw
+                : raw && typeof raw === 'object' && Array.isArray(raw.entries)
+                    ? raw.entries
+                    : [];
+            let changed = false;
+            for (const entry of entries) {
+                const key = typeof entry?.key === 'string' ? entry.key : undefined;
+                const seenAt = typeof entry?.seenAt === 'number' ? entry.seenAt : undefined;
+                if (!key || seenAt === undefined || !Number.isFinite(seenAt) || now - seenAt > this.dedupTtlMs) {
+                    changed = true;
+                    continue;
+                }
+                this.durableMessageIds.set(key, seenAt);
+            }
+            if (changed)
+                this.persistDurableDedup();
+        }
+        catch (error) {
+            logger.warn(`[Queue] Failed to restore durable dedup ledger: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    persistDurableDedup() {
+        if (!this.dedupPath)
+            return;
+        const now = Date.now();
+        for (const [key, seenAt] of this.durableMessageIds) {
+            if (now - seenAt > this.dedupTtlMs)
+                this.durableMessageIds.delete(key);
+        }
+        try {
+            fs.mkdirSync(path.dirname(this.dedupPath), { recursive: true });
+            const tmp = `${this.dedupPath}.tmp-${process.pid}-${Date.now()}`;
+            fs.writeFileSync(tmp, JSON.stringify({ version: 1, updatedAt: now, entries: [...this.durableMessageIds].map(([key, seenAt]) => ({ key, seenAt })) }));
+            fs.renameSync(tmp, this.dedupPath);
+        }
+        catch (error) {
+            logger.warn(`[Queue] Failed to persist durable dedup ledger: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    hasEnqueuedMessage(sessionKey, messageId, selfAID) {
         for (const [queueKey, queue] of this.queues) {
             if (!this.matchesSession(queueKey, sessionKey))
                 continue;
-            if (queue.some(item => this.messageIdsFor(item).includes(messageId)))
+            if (queue.some(item => this.partsOf(item).some(part => this.partMatchesMessage(part, messageId, selfAID, queueKey))))
                 return true;
         }
         for (const [queueKey, active] of this.activeBatches) {
             if (!this.matchesSession(queueKey, sessionKey))
                 continue;
-            if (this.messageIdsFor(active).includes(messageId))
+            if (this.partsOf(active).some(part => this.partMatchesMessage(part, messageId, selfAID, queueKey)))
                 return true;
         }
         return false;
@@ -143,7 +208,7 @@ export class MessageQueue {
     forgetProcessed(sessionKey, message) {
         if (!message.messageId)
             return;
-        this.recentMessageIds.delete(`${sessionKey}:${message.messageId}`);
+        this.recentMessageIds.delete(this.dedupKey(sessionKey, message.messageId, message.selfAID));
     }
     /**
      * 检查队列 key 是否属于指定 sessionKey
@@ -160,6 +225,10 @@ export class MessageQueue {
         const prefix = selfAID ? `${selfAID}::` : '';
         return `${prefix}${sessionKey}::${normalized}`;
     }
+    selfAIDFromQueueKey(queueKey) {
+        const parts = queueKey.split('::');
+        return parts.length >= 3 ? parts[0] : undefined;
+    }
     sessionKeyFromQueueKey(queueKey) {
         // 格式：selfAID::sessionKey::projectPath 或 sessionKey::projectPath（旧格式兼容）
         const parts = queueKey.split('::');
@@ -181,6 +250,7 @@ export class MessageQueue {
             role: item.role,
             resolve: item.resolve,
             reject: item.reject,
+            enqueuedAt: item.enqueuedAt ?? item.message.enqueuedAt,
         };
     }
     itemFromPart(part) {
@@ -191,6 +261,7 @@ export class MessageQueue {
             role: part.role,
             resolve: part.resolve,
             reject: part.reject,
+            enqueuedAt: part.enqueuedAt ?? part.message.enqueuedAt,
         };
     }
     partsOf(item) {
@@ -207,21 +278,37 @@ export class MessageQueue {
             .map(part => part.message.messageId)
             .filter((id) => !!id);
     }
+    partMatchesMessage(part, messageId, selfAID, queueKey) {
+        if (part.message.messageId !== messageId)
+            return false;
+        if (selfAID === undefined)
+            return true;
+        const messageScope = part.message.selfAID ?? (queueKey ? this.selfAIDFromQueueKey(queueKey) : undefined);
+        return messageScope === selfAID;
+    }
     peerIdsFor(item) {
         return this.partsOf(item).map(part => part.message.peerId);
     }
-    serializePart(part, enqueuedAt) {
+    serializePart(part, fallbackEnqueuedAt) {
+        const enqueuedAt = part.enqueuedAt ?? part.message.enqueuedAt ?? fallbackEnqueuedAt ?? Date.now();
+        const message = part.message.enqueuedAt === enqueuedAt
+            ? part.message
+            : { ...part.message, enqueuedAt };
         return {
-            message: part.message,
+            message,
             projectPath: part.projectPath,
             agentName: part.agentName,
             role: part.role,
             enqueuedAt,
         };
     }
-    serializeItem(item, enqueuedAt) {
+    serializeItem(item, fallbackEnqueuedAt) {
+        const enqueuedAt = item.enqueuedAt ?? item.message.enqueuedAt ?? fallbackEnqueuedAt ?? Date.now();
+        const message = item.message.enqueuedAt === enqueuedAt
+            ? item.message
+            : { ...item.message, enqueuedAt };
         return {
-            message: item.message,
+            message,
             projectPath: item.projectPath,
             agentName: item.agentName,
             role: item.role,
@@ -230,17 +317,25 @@ export class MessageQueue {
         };
     }
     restoredPart(item) {
+        const enqueuedAt = item.enqueuedAt ?? item.message.enqueuedAt;
+        const message = enqueuedAt === undefined
+            ? this.normalizeRestoredMessage(item.message)
+            : this.normalizeRestoredMessage({ ...item.message, enqueuedAt });
         return {
-            message: this.normalizeRestoredMessage(item.message),
+            message,
             projectPath: item.projectPath,
             agentName: item.agentName || DEFAULT_AGENT_NAME,
             role: item.role,
             resolve: () => { },
             reject: () => { },
+            enqueuedAt,
         };
     }
     restoreSubmittedPart(item) {
-        const source = this.normalizeRestoredMessage(item.message);
+        const sourceEnqueuedAt = item.enqueuedAt ?? item.message.enqueuedAt;
+        const source = this.normalizeRestoredMessage(sourceEnqueuedAt === undefined
+            ? item.message
+            : { ...item.message, enqueuedAt: sourceEnqueuedAt });
         const message = {
             ...source,
             content: RESTART_RESUME_CONTENT,
@@ -272,6 +367,7 @@ export class MessageQueue {
             role: item.role,
             resolve: () => { },
             reject: () => { },
+            enqueuedAt: sourceEnqueuedAt,
         };
     }
     normalizeRestoredMessage(message) {
@@ -299,9 +395,53 @@ export class MessageQueue {
             role: this.highestRole(parts),
             resolve: () => parts.forEach(part => part.resolve()),
             reject: (error) => parts.forEach(part => part.reject(error)),
+            enqueuedAt: this.earliestPartEnqueuedAt(parts),
             parts,
         };
     }
+    firstEnqueuedAt(item) {
+        const parts = 'parts' in item && item.parts ? item.parts : [item];
+        let value;
+        for (const part of parts) {
+            const candidate = part.enqueuedAt ?? part.message.enqueuedAt;
+            if (candidate === undefined)
+                continue;
+            value = value === undefined ? candidate : Math.min(value, candidate);
+        }
+        return value;
+    }
+    earliestEnqueuedAt(items) {
+        let value;
+        for (const item of items) {
+            const candidate = this.firstEnqueuedAt(item);
+            if (candidate === undefined)
+                continue;
+            value = value === undefined ? candidate : Math.min(value, candidate);
+        }
+        return value;
+    }
+    earliestPartEnqueuedAt(parts) {
+        let value;
+        for (const part of parts) {
+            const candidate = part.enqueuedAt ?? part.message.enqueuedAt;
+            if (candidate === undefined)
+                continue;
+            value = value === undefined ? candidate : Math.min(value, candidate);
+        }
+        return value;
+    }
+    firstReceivedAt(items) {
+        let value;
+        for (const item of items) {
+            for (const part of this.partsOf(item)) {
+                const candidate = part.message.receivedAt ?? part.message.timestamp;
+                if (candidate === undefined)
+                    continue;
+                value = value === undefined ? candidate : Math.min(value, candidate);
+            }
+        }
+        return value;
+    }
     highestRole(items) {
         const rank = {
             none: 0,
@@ -431,19 +571,18 @@ export class MessageQueue {
         try {
             const buckets = [];
             const activeBuckets = [];
-            const enqueuedAt = Date.now();
             for (const [queueKey, queue] of this.queues.entries()) {
                 if (queue.length === 0)
                     continue;
                 buckets.push({
                     queueKey,
-                    items: queue.map(item => this.serializeItem(item, enqueuedAt)),
+                    items: queue.map(item => this.serializeItem(item)),
                 });
             }
             for (const [queueKey, item] of this.activeBatches.entries()) {
                 activeBuckets.push({
                     queueKey,
-                    items: [this.serializeItem(item, enqueuedAt)],
+                    items: [this.serializeItem(item)],
                 });
             }
             fs.mkdirSync(path.dirname(this.persistencePath), { recursive: true });
@@ -496,13 +635,15 @@ export class MessageQueue {
             if (parts.length === 0)
                 continue;
             const rawParts = parts
-                .sort((a, b) => (a.message.timestamp ?? 0) - (b.message.timestamp ?? 0));
+                .sort((a, b) => (a.message.receivedAt ?? a.message.timestamp ?? 0)
+                - (b.message.receivedAt ?? b.message.timestamp ?? 0));
             for (const part of rawParts) {
                 const rawItem = this.itemFromPart(part);
                 queue.push(rawItem);
                 if (rawItem.message.messageId) {
-                    const dedupKey = `${sessionKey}:${rawItem.message.messageId}`;
+                    const dedupKey = this.dedupKey(sessionKey, rawItem.message.messageId, rawItem.message.selfAID);
                     this.recentMessageIds.add(dedupKey);
+                    this.durableMessageIds.set(dedupKey, Date.now());
                     setTimeout(() => this.recentMessageIds.delete(dedupKey), this.DEDUP_WINDOW);
                 }
             }
@@ -538,13 +679,15 @@ export class MessageQueue {
                 : this.itemFromPart(first.message.handoffDelivery
                     ? this.restoredPart(first)
                     : this.restoreSubmittedPart(first));
-            submittedItem.message.timestamp = first.message.timestamp;
+            submittedItem.message.timestamp = first.message.receivedAt ?? first.message.timestamp;
+            submittedItem.message.enqueuedAt = first.enqueuedAt ?? first.message.enqueuedAt;
             queue.push(submittedItem);
             for (const part of rawParts) {
                 if (!part.message.messageId)
                     continue;
-                const dedupKey = `${sessionKey}:${part.message.messageId}`;
+                const dedupKey = this.dedupKey(sessionKey, part.message.messageId, part.message.selfAID);
                 this.recentMessageIds.add(dedupKey);
+                this.durableMessageIds.set(dedupKey, Date.now());
                 setTimeout(() => this.recentMessageIds.delete(dedupKey), this.DEDUP_WINDOW);
             }
             restored += rawParts.length;
@@ -564,6 +707,27 @@ export class MessageQueue {
                 logger.warn('[Queue] Ignoring unsupported persisted queue file');
                 return 0;
             }
+            // Version-1 snapshots did not carry per-item enqueue times. Preserve
+            // their last durable snapshot time instead of making restored history
+            // look newly queued at the moment of daemon restart.
+            const legacyEnqueuedAt = typeof parsed.updatedAt === 'number' && Number.isFinite(parsed.updatedAt)
+                ? parsed.updatedAt
+                : Date.now();
+            for (const bucket of [...parsed.queues, ...(Array.isArray(parsed.active) ? parsed.active : [])]) {
+                for (const item of bucket.items ?? []) {
+                    if (!item?.message)
+                        continue;
+                    if (item.enqueuedAt === undefined && item.message?.enqueuedAt === undefined)
+                        item.enqueuedAt = legacyEnqueuedAt;
+                    for (const part of item.parts ?? []) {
+                        if (!part?.message)
+                            continue;
+                        if (part.enqueuedAt === undefined && part.message?.enqueuedAt === undefined) {
+                            part.enqueuedAt = item.enqueuedAt ?? legacyEnqueuedAt;
+                        }
+                    }
+                }
+            }
             const restoredKeys = new Set();
             if (Array.isArray(parsed.active)) {
                 for (const bucket of parsed.active) {
@@ -574,6 +738,7 @@ export class MessageQueue {
                 restored += this.restoreBucket(bucket, restoredKeys);
             }
             this.persistQueuesImmediate();
+            this.persistDurableDedup();
             if (restored > 0) {
                 logger.info(`[Queue] Restored ${restored} persisted message(s) from ${this.persistencePath}`);
             }
@@ -617,8 +782,13 @@ export class MessageQueue {
         if (options?.signal?.aborted) {
             return Promise.reject(abortError(options.signal.reason));
         }
+        if (options?.selfAID && message.selfAID !== options.selfAID) {
+            // The queue option is the authoritative physical-copy scope. A shared
+            // broadcast object must be cloned per agent before dedup/cancel logic.
+            message = { ...message, selfAID: options.selfAID };
+        }
         // 消息去重检查
-        if (!this.shouldProcess(sessionKey, message)) {
+        if (!this.shouldProcess(sessionKey, message, options?.selfAID)) {
             options?.onPersisted?.();
             return Promise.resolve();
         }
@@ -676,7 +846,18 @@ export class MessageQueue {
             const queue = this.queues.get(queueKey);
             const queuedResolve = options?.resolveOnPersist ? cleanupAbort : resolveOnce;
             const queuedReject = options?.resolveOnPersist ? cleanupAbort : rejectOnce;
-            const queuedItem = { message, projectPath, agentName, role: options?.role, resolve: queuedResolve, reject: queuedReject };
+            // Capture the physical enqueue instant once. It must not be regenerated
+            // on every persistence snapshot, otherwise old messages appear fresh.
+            const enqueuedAt = Date.now();
+            // Clone at the physical queue boundary. The same inbound object may be
+            // broadcast to multiple agents; mutating it would make all copies share
+            // the last queue's enqueue timestamp.
+            message = {
+                ...message,
+                enqueuedAt,
+                timestamp: message.receivedAt ?? message.timestamp ?? enqueuedAt,
+            };
+            const queuedItem = { message, projectPath, agentName, role: options?.role, resolve: queuedResolve, reject: queuedReject, enqueuedAt };
             queue.push(queuedItem);
             this.logicalQueue.enqueue(queueKey, message); // 通知逻辑队列记录出队顺序
             abortHandler = () => {
@@ -693,7 +874,7 @@ export class MessageQueue {
                     this.persistQueuesImmediate();
                 }
                 else if (message.messageId) {
-                    void this.cancelActiveAndWait(message.messageId).finally(() => {
+                    void this.cancelActiveAndWait(message.messageId, message.selfAID).finally(() => {
                         this.forgetProcessed(sessionKey, message);
                         settleReject(error);
                     });
@@ -715,6 +896,10 @@ export class MessageQueue {
                 rejectOnce(new Error('failed to persist message queue'));
                 return;
             }
+            // A duplicate must not re-enter a runner after the queue entry has
+            // survived its write-ahead snapshot. Keep this separate from the queue
+            // snapshot because the latter is removed as soon as the task completes.
+            this.rememberDurably(sessionKey, message, options?.selfAID);
             try {
                 options?.onPersisted?.();
             }
@@ -851,6 +1036,7 @@ export class MessageQueue {
                     role: this.highestRole(rawParts),
                     resolve: () => rawParts.forEach(part => part.resolve()),
                     reject: (error) => rawParts.forEach(part => part.reject(error)),
+                    enqueuedAt: this.earliestPartEnqueuedAt(rawParts),
                     parts: rawParts,
                 };
             const batchRole = this.commonRole(rawItems);
@@ -866,6 +1052,7 @@ export class MessageQueue {
             const activeState = {
                 baseagent: merged.message.baseagent,
                 peerId: this.uniquePeerId(rawItems),
+                selfAID: merged.message.selfAID ?? this.selfAIDFromQueueKey(queueKey),
                 messageIds: activeMessageIds,
             };
             this.activeStates.set(queueKey, activeState);
@@ -991,7 +1178,7 @@ export class MessageQueue {
         const parts = this.partsOf(item);
         let ts = Number.POSITIVE_INFINITY;
         for (const part of parts)
-            ts = Math.min(ts, part.message.timestamp ?? 0);
+            ts = Math.min(ts, part.message.receivedAt ?? part.message.timestamp ?? 0);
         return Number.isFinite(ts) ? ts : 0;
     }
     /**
@@ -1073,6 +1260,8 @@ export class MessageQueue {
                     sameDevice: m.sameDevice, sameNetwork: m.sameNetwork, sameEgressIp: m.sameEgressIp,
                     encrypted: m.encrypted,
                     content: m.content, timestamp: m.timestamp,
+                    receivedAt: m.receivedAt,
+                    gatewaySeq: m.gatewaySeq,
                     causation: m.causation,
                     images: m.images && m.images.length > 0 ? m.images : undefined,
                     mentions: m.mentions && m.mentions.length > 0 ? m.mentions : undefined,
@@ -1090,6 +1279,8 @@ export class MessageQueue {
                 break;
             }
         }
+        const firstReceivedAt = this.firstReceivedAt(items);
+        const earliestEnqueuedAt = this.earliestEnqueuedAt(items);
         const merged = {
             ...last.message,
             content: contents.join('\n'),
@@ -1098,6 +1289,9 @@ export class MessageQueue {
             mentions: allMentions.length > 0 ? allMentions : undefined,
             messageId: latestMessageId,
             sourceMessageIds: sourceMessageIds.length > 0 ? sourceMessageIds : undefined,
+            receivedAt: firstReceivedAt,
+            timestamp: firstReceivedAt ?? last.message.timestamp,
+            enqueuedAt: earliestEnqueuedAt,
             // 密文优先：合并批次内任一条密文，则整轮（interactive 自动回复的单值出站）按密文。
             // 任一条 encrypted===true 即 true；否则若有明确的 false 则 false；全 undefined（非 aun）则 undefined。
             encrypted: subMessages.some(s => s.encrypted === true)
@@ -1122,6 +1316,7 @@ export class MessageQueue {
             agentName: last.agentName,
             resolve: () => { }, // 由调用方管理
             reject: () => { },
+            enqueuedAt: earliestEnqueuedAt,
         };
     }
     getQueueLength(sessionKey) {
@@ -1157,14 +1352,14 @@ export class MessageQueue {
         }
         return false;
     }
-    cancel(messageId) {
-        for (const queue of this.queues.values()) {
-            const idx = queue.findIndex(q => this.messageIdsFor(q).includes(messageId));
+    cancel(messageId, selfAID) {
+        for (const [queueKey, queue] of this.queues.entries()) {
+            const idx = queue.findIndex(q => this.partsOf(q).some(part => this.partMatchesMessage(part, messageId, selfAID, queueKey)));
             if (idx === -1)
                 continue;
             const target = queue[idx];
             const parts = this.partsOf(target);
-            const partIdx = parts.findIndex(part => part.message.messageId === messageId);
+            const partIdx = parts.findIndex(part => this.partMatchesMessage(part, messageId, selfAID, queueKey));
             if (partIdx === -1)
                 continue;
             if (parts.length === 1) {
@@ -1186,26 +1381,31 @@ export class MessageQueue {
      * 撤回正在执行的消息：如果 messageId 正在处理中，触发 interrupt。
      * @returns true 如果找到并触发了中断
      */
-    cancelActive(messageId) {
-        const cancellation = this.beginActiveCancellation(messageId);
+    cancelActive(messageId, selfAID) {
+        const cancellation = this.beginActiveCancellation(messageId, selfAID);
         if (cancellation.barrier)
             void cancellation.barrier;
         return cancellation.found;
     }
     /** Cancel an active message and wait until the runner interrupt barrier settles. */
-    async cancelActiveAndWait(messageId) {
-        const cancellation = this.beginActiveCancellation(messageId);
+    async cancelActiveAndWait(messageId, selfAID) {
+        const cancellation = this.beginActiveCancellation(messageId, selfAID);
         await cancellation.barrier;
         return cancellation.found;
     }
-    beginActiveCancellation(messageId) {
+    beginActiveCancellation(messageId, selfAID) {
         for (const [queueKey, activeState] of this.activeStates.entries()) {
             if (!activeState.messageIds.has(messageId))
                 continue;
+            if (selfAID !== undefined && activeState.selfAID !== selfAID)
+                continue;
             const active = this.activeBatches.get(queueKey);
-            if (active && this.messageIdsFor(active).includes(messageId)) {
+            if (active && !this.partsOf(active).some(part => this.partMatchesMessage(part, messageId, selfAID, queueKey))) {
+                continue;
+            }
+            if (active && this.partsOf(active).some(part => this.partMatchesMessage(part, messageId, selfAID, queueKey))) {
                 const parts = this.partsOf(active);
-                const remaining = parts.filter(part => part.message.messageId !== messageId);
+                const remaining = parts.filter(part => !this.partMatchesMessage(part, messageId, selfAID, queueKey));
                 if (remaining.length === 0) {
                     this.activeBatches.delete(queueKey);
                     this.processingStartTime.delete(queueKey);
@@ -1439,9 +1639,14 @@ export class MessageQueue {
     buildSnapshot(status, queueKey, sessionKey, item) {
         const { channelType, channelId } = this.parseSessionKey(sessionKey);
         const startTime = this.processingStartTime.get(queueKey);
+        const receivedAt = item.message.receivedAt ?? item.message.timestamp;
+        const enqueuedAt = this.firstEnqueuedAt(item);
         const elapsedMs = status === 'active' && startTime != null
             ? Date.now() - startTime
             : undefined;
+        const queueWaitMs = enqueuedAt == null
+            ? undefined
+            : Math.max(0, (status === 'active' && startTime != null ? startTime : Date.now()) - enqueuedAt);
         return {
             status,
             sessionKey,
@@ -1451,9 +1656,26 @@ export class MessageQueue {
             peerName: item.message.peerName,
             preview: this.truncatePreview(item.message.content),
             messageId: item.message.messageId,
+            receivedAt,
+            gatewaySeq: item.message.gatewaySeq,
+            enqueuedAt,
+            queueWaitMs,
+            processingStartedAt: status === 'active' ? startTime : undefined,
             elapsedMs,
         };
     }
+    matchesTimeRange(item, range) {
+        if (!range || (range.after === undefined && range.before === undefined))
+            return true;
+        const value = item.message.receivedAt ?? item.message.timestamp ?? item.message.enqueuedAt ?? this.firstEnqueuedAt(item);
+        if (value === undefined)
+            return false;
+        if (range.after !== undefined && value <= range.after)
+            return false;
+        if (range.before !== undefined && value >= range.before)
+            return false;
+        return true;
+    }
     /**
      * 通过 human-readable sessionKey 反查 sessionId（cli interrupt 用）
      */
@@ -1469,7 +1691,7 @@ export class MessageQueue {
      * @param sessionId - Session.id（meta_YYYYMMDD_TS）
      * @returns 仅返回 pending 状态的消息
      */
-    getQueueItemsBySession(sessionId) {
+    getQueueItemsBySession(sessionId, range) {
         const result = [];
         for (const [queueKey, queue] of this.queues.entries()) {
             if (!this.matchesSession(queueKey, sessionId))
@@ -1477,6 +1699,8 @@ export class MessageQueue {
             const sessionKey = this.queueKeyToSessionKey.get(queueKey)
                 || this.sessionKeyFromQueueKey(queueKey);
             for (const item of queue) {
+                if (!this.matchesTimeRange(item, range))
+                    continue;
                 result.push(this.buildSnapshot('pending', queueKey, sessionKey, item));
             }
         }
@@ -1487,13 +1711,15 @@ export class MessageQueue {
      * @param agentName - agent 内部名称
      * @returns 返回所有状态（active + pending）的消息
      */
-    getQueueItemsByAgent(agentName) {
+    getQueueItemsByAgent(agentName, range) {
         const result = [];
         // active 项
         for (const [queueKey, item] of this.activeBatches.entries()) {
             const itemAgent = item.agentName || DEFAULT_AGENT_NAME;
             if (itemAgent !== agentName)
                 continue;
+            if (!this.matchesTimeRange(item, range))
+                continue;
             const sessionKey = this.queueKeyToSessionKey.get(queueKey)
                 || this.sessionKeyFromQueueKey(queueKey);
             result.push(this.buildSnapshot('active', queueKey, sessionKey, item));
@@ -1504,6 +1730,8 @@ export class MessageQueue {
                 const itemAgent = item.agentName || DEFAULT_AGENT_NAME;
                 if (itemAgent !== agentName)
                     continue;
+                if (!this.matchesTimeRange(item, range))
+                    continue;
                 const sessionKey = this.queueKeyToSessionKey.get(queueKey)
                     || this.sessionKeyFromQueueKey(queueKey);
                 result.push(this.buildSnapshot('pending', queueKey, sessionKey, item));