evolcore 0.0.20 → 0.0.22

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

@@ -3,6 +3,7 @@ import fs from 'fs';
 import { logger } from '../../utils/logger.js';
 import { LogicalQueueBridge } from './logical-queue-bridge.js';
 import { normalizeCausation } from '../causation/context.js';
+import { KeyedFairMutex } from '../handoff/mutex.js';
 const DEFAULT_AGENT_NAME = '<unknown>';
 const RESTART_RESUME_CONTENT = 'evolcore 服务已重启，请继续之前未完成的任务。';
 export class MessageQueue {
@@ -10,6 +11,9 @@ export class MessageQueue {
     processing = new Set();
     processingAgent = new Map(); // queueKey → agentName（处理中项目的 agent）
     externalLocks = new Map();
+    prequeueReservations = new Map();
+    /** Serializes fast session commands while retaining the existing dequeue gate. */
+    sessionBarrierMutex = new KeyedFairMutex();
     handler;
     activeStates = new Map(); // queueKey → active task state
     interruptCallback;
@@ -32,6 +36,7 @@ export class MessageQueue {
     shutdownPromise;
     /** 逻辑队列桥接：管理出队顺序（响应模式可注入自定义策略，默认 FIFO） */
     logicalQueue = new LogicalQueueBridge();
+    enqueueSequence = 0;
     constructor(handler, options) {
         this.handler = handler;
         this.persistencePath = options?.persistencePath;
@@ -83,6 +88,17 @@ export class MessageQueue {
                 this.markActiveTerminal(event.sessionId, event.reason || 'interrupted');
             }
         });
+        subscribe.call(eventBus, 'task:started', event => {
+            if (!('sessionId' in event) || !event.sessionId)
+                return;
+            const taskEvent = event;
+            for (const [queueKey, state] of this.activeStates) {
+                if (this.matchesSession(queueKey, taskEvent.sessionId)) {
+                    state.taskId = taskEvent.taskId;
+                    state.generation = taskEvent.generation;
+                }
+            }
+        });
         subscribe.call(eventBus, 'task:completed', event => {
             if ('sessionId' in event && event.sessionId)
                 this.markActiveTerminal(event.sessionId, 'completed');
@@ -138,6 +154,42 @@ export class MessageQueue {
         setTimeout(() => this.recentMessageIds.delete(dedupKey), this.DEDUP_WINDOW);
         return true;
     }
+    /**
+     * Claim a stable inbound message for a fast command that bypasses the
+     * normal queue.  The claim uses exactly the same durable ledger and key as
+     * ordinary enqueue deduplication, but deliberately does not enqueue or
+     * affect queue scheduling.
+     */
+    claimInbound(sessionKey, messageId, selfAID) {
+        const normalizedMessageId = messageId.trim();
+        if (!normalizedMessageId) {
+            const error = new Error('inbound claim requires a stable messageId');
+            error.code = 'INBOUND_MESSAGE_ID_REQUIRED';
+            throw error;
+        }
+        const key = this.dedupKey(sessionKey, normalizedMessageId, selfAID);
+        if (this.recentMessageIds.has(key)
+            || this.durableMessageIds.has(key)
+            || this.hasEnqueuedMessage(sessionKey, normalizedMessageId, selfAID)) {
+            return 'duplicate';
+        }
+        if (!this.dedupPath) {
+            const error = new Error('durable inbound dedup is unavailable');
+            error.code = 'INBOUND_DEDUP_UNAVAILABLE';
+            throw error;
+        }
+        const seenAt = Date.now();
+        this.durableMessageIds.set(key, seenAt);
+        if (!this.persistDurableDedup()) {
+            this.durableMessageIds.delete(key);
+            const error = new Error('failed to persist inbound dedup claim');
+            error.code = 'INBOUND_DEDUP_PERSIST_FAILED';
+            throw error;
+        }
+        this.recentMessageIds.add(key);
+        setTimeout(() => this.recentMessageIds.delete(key), this.DEDUP_WINDOW);
+        return 'claimed';
+    }
     rememberDurably(sessionKey, message, selfAID) {
         if (!this.dedupPath || !message.messageId)
             return;
@@ -174,20 +226,64 @@ export class MessageQueue {
     }
     persistDurableDedup() {
         if (!this.dedupPath)
-            return;
+            return false;
         const now = Date.now();
         for (const [key, seenAt] of this.durableMessageIds) {
             if (now - seenAt > this.dedupTtlMs)
                 this.durableMessageIds.delete(key);
         }
+        const tmp = `${this.dedupPath}.tmp-${process.pid}-${Date.now()}-${this.enqueueSequence}`;
+        let fd;
         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 })) }));
+            const content = Buffer.from(JSON.stringify({
+                version: 1,
+                updatedAt: now,
+                entries: [...this.durableMessageIds].map(([key, seenAt]) => ({ key, seenAt })),
+            }));
+            fd = fs.openSync(tmp, 'w');
+            let offset = 0;
+            while (offset < content.length) {
+                const written = fs.writeSync(fd, content, offset, content.length - offset, null);
+                if (written <= 0)
+                    throw new Error('dedup ledger write made no progress');
+                offset += written;
+            }
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
             fs.renameSync(tmp, this.dedupPath);
+            const persistedFd = fs.openSync(this.dedupPath, 'r');
+            try {
+                fs.fsyncSync(persistedFd);
+            }
+            finally {
+                fs.closeSync(persistedFd);
+            }
+            if (process.platform !== 'win32') {
+                const directoryFd = fs.openSync(path.dirname(this.dedupPath), 'r');
+                try {
+                    fs.fsyncSync(directoryFd);
+                }
+                finally {
+                    fs.closeSync(directoryFd);
+                }
+            }
+            return true;
         }
         catch (error) {
             logger.warn(`[Queue] Failed to persist durable dedup ledger: ${error instanceof Error ? error.message : String(error)}`);
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { }
+            }
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { }
+            return false;
         }
     }
     hasEnqueuedMessage(sessionKey, messageId, selfAID) {
@@ -538,6 +634,8 @@ export class MessageQueue {
                 sessionId: sessionKey,
                 reason: 'daemon_restart',
                 agentName,
+                taskId: this.activeStates.get(queueKey)?.taskId,
+                generation: this.activeStates.get(queueKey)?.generation,
                 causation: item.message.causation,
             });
             barriers.push(this.triggerInterrupt(queueKey, sessionKey, this.activeStates.get(queueKey)?.baseagent, agentName, 'daemon_restart'));
@@ -768,6 +866,8 @@ export class MessageQueue {
     shouldRestoreMessage(message, sessionId) {
         // The Trigger scheduler records open runs as daemon_restart. Replaying their
         // queued work afterwards would execute side effects for an already-failed run.
+        if (message.executionPermissionOverride)
+            return false;
         if (message.source !== 'trigger' && !message.triggerMeta)
             return true;
         this.droppedTriggerSessionIds.add(sessionId);
@@ -794,9 +894,9 @@ export class MessageQueue {
         }
         // 拦截器检查：AskUserQuestion 等场景的一次性消息拦截
         const interceptor = this.interceptors.get(sessionKey);
-        const canAnswerInteraction = message.source === undefined
+        const canAnswerInteraction = !message.executionPermissionOverride && (message.source === undefined
             || message.source === 'user'
-            || message.source === 'card-trigger';
+            || message.source === 'card-trigger');
         if (interceptor && canAnswerInteraction) {
             this.interceptors.delete(sessionKey);
             logger.debug(`[Queue] Message intercepted for ${sessionKey}`);
@@ -849,6 +949,7 @@ export class MessageQueue {
             // Capture the physical enqueue instant once. It must not be regenerated
             // on every persistence snapshot, otherwise old messages appear fresh.
             const enqueuedAt = Date.now();
+            this.enqueueSequence += 1;
             // 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.
@@ -934,6 +1035,8 @@ export class MessageQueue {
                         sessionId: sessionKey,
                         reason: 'new_message',
                         agentName: this.processingAgent.get(queueKey),
+                        taskId: this.activeStates.get(queueKey)?.taskId,
+                        generation: this.activeStates.get(queueKey)?.generation,
                         causation: this.activeBatches.get(queueKey)?.message.causation,
                     });
                     if (this.interruptCallback) {
@@ -1154,7 +1257,10 @@ export class MessageQueue {
         return result;
     }
     isMergeBarrier(message) {
-        return !!message.handoffDelivery || !!message.triggerMeta || !!message.causation?.trigger?.path.length;
+        return !!message.executionPermissionOverride
+            || !!message.handoffDelivery
+            || !!message.triggerMeta
+            || !!message.causation?.trigger?.path.length;
     }
     isOriginHandoff(message) {
         return message.source === 'handoff' && message.handoffDelivery?.direction === 'origin';
@@ -1427,6 +1533,8 @@ export class MessageQueue {
                 sessionId: sessionKey,
                 reason: 'recalled',
                 agentName,
+                taskId: activeState?.taskId,
+                generation: activeState?.generation,
                 causation: active?.message.causation,
             });
             const barrier = this.interruptCallback
@@ -1437,23 +1545,122 @@ export class MessageQueue {
         return { found: false, barrier: Promise.resolve() };
     }
     /**
-     * 外部锁：快速命令（/compact, /clear）执行期间阻塞队列处理
-     * 返回 release 函数
+     * Capture the session's queue state and install a dequeue gate in one
+     * synchronous critical section.  Messages arriving after this call remain
+     * durable in the queue, but processNext will wait until the last holder
+     * releases the gate.
      */
-    acquireLock(sessionKey) {
-        let releaseFn;
-        const promise = new Promise(resolve => { releaseFn = resolve; });
-        this.externalLocks.set(sessionKey, promise);
+    acquireDequeueGate(sessionKey) {
+        const existing = this.externalLocks.get(sessionKey);
+        if (existing) {
+            existing.holders += 1;
+            let released = false;
+            return {
+                snapshot: { ...existing.snapshot },
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    existing.holders -= 1;
+                    if (existing.holders > 0)
+                        return;
+                    if (this.externalLocks.get(sessionKey) === existing)
+                        this.externalLocks.delete(sessionKey);
+                    existing.releasePromise();
+                },
+            };
+        }
+        let releasePromise;
+        const promise = new Promise(resolve => { releasePromise = resolve; });
+        let queued = 0;
+        let active = false;
+        let dispatching = false;
+        for (const [queueKey, queue] of this.queues.entries()) {
+            if (!this.matchesSession(queueKey, sessionKey))
+                continue;
+            queued += this.queueRawMessageCount(queue);
+            if (this.processing.has(queueKey) || this.activeBatches.has(queueKey))
+                active = true;
+            if (this.processing.has(queueKey) && !this.activeBatches.has(queueKey))
+                dispatching = true;
+        }
+        for (const queueKey of this.activeBatches.keys()) {
+            if (this.matchesSession(queueKey, sessionKey))
+                active = true;
+        }
+        const state = {
+            promise,
+            releasePromise,
+            holders: 1,
+            snapshot: {
+                prequeue: this.prequeueReservations.get(sessionKey) ?? 0,
+                active,
+                queued,
+                dispatching,
+                cutoff: this.enqueueSequence,
+            },
+        };
+        this.externalLocks.set(sessionKey, state);
+        let released = false;
+        return {
+            snapshot: { ...state.snapshot },
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                state.holders -= 1;
+                if (state.holders > 0)
+                    return;
+                if (this.externalLocks.get(sessionKey) === state)
+                    this.externalLocks.delete(sessionKey);
+                state.releasePromise();
+            },
+        };
+    }
+    /**
+     * Mark an admitted message before it enters debounce or other pre-queue
+     * work. The returned release is idempotent so callers can use it both from
+     * onPersisted and a surrounding finally block.
+     */
+    reserveSessionIngress(sessionKey) {
+        this.prequeueReservations.set(sessionKey, (this.prequeueReservations.get(sessionKey) ?? 0) + 1);
+        let released = false;
         return () => {
-            this.externalLocks.delete(sessionKey);
-            releaseFn();
+            if (released)
+                return;
+            released = true;
+            const remaining = (this.prequeueReservations.get(sessionKey) ?? 1) - 1;
+            if (remaining > 0)
+                this.prequeueReservations.set(sessionKey, remaining);
+            else
+                this.prequeueReservations.delete(sessionKey);
         };
     }
+    /**
+     * Run a fast session command while no queued work can start.  The queue
+     * snapshot and external gate are installed before the callback is invoked;
+     * messages arriving afterwards remain durable but are outside this probe.
+     */
+    async withSessionBarrier(sessionKey, callback) {
+        return this.sessionBarrierMutex.forKey(sessionKey).runExclusive(async () => {
+            const gate = this.acquireDequeueGate(sessionKey);
+            try {
+                return await callback(gate.snapshot);
+            }
+            finally {
+                gate.release();
+            }
+        });
+    }
+    /** Backwards-compatible lock API used by existing quick commands. */
+    acquireLock(sessionKey) {
+        return this.acquireDequeueGate(sessionKey).release;
+    }
     /** 检查是否有外部锁 */
     getExternalLock(queueKey) {
-        for (const [key, promise] of this.externalLocks) {
+        for (const [key, state] of this.externalLocks) {
             if (this.matchesSession(queueKey, key))
-                return promise;
+                return state.promise;
         }
         return undefined;
     }
@@ -1576,6 +1783,8 @@ export class MessageQueue {
                     sessionId: sessionKey,
                     reason: 'stop',
                     agentName: name,
+                    taskId: this.activeStates.get(queueKey)?.taskId,
+                    generation: this.activeStates.get(queueKey)?.generation,
                     causation: this.activeBatches.get(queueKey)?.message.causation,
                 });
                 if (this.interruptCallback) {
@@ -1848,6 +2057,8 @@ export class MessageQueue {
             sessionId: sessionKey,
             reason: 'new_message',
             agentName: targetAgentName,
+            taskId: this.activeStates.get(targetQueueKey)?.taskId,
+            generation: this.activeStates.get(targetQueueKey)?.generation,
             causation: this.activeBatches.get(targetQueueKey)?.message.causation,
         });
         if (this.interruptCallback) {

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

@@ -4,6 +4,12 @@
  * 从 message-processor.ts 提取的独立工具函数，供 ResponseEngine 和其他模块使用。
  */
 import { renderCommandCardAsText, renderActionAsText } from '../interaction-router.js';
+/** A legacy adapter resolved its send call without providing a structured receipt. */
+export const LEGACY_INTERACTION_ACCEPTED = 'legacy-accepted';
+export function isInteractionSendAccepted(result) {
+    return result === LEGACY_INTERACTION_ACCEPTED
+        || (result !== false && (result.status === 'sent' || result.status === 'queued'));
+}
 /**
  * 构造出站消息信封
  */
@@ -129,7 +135,8 @@ export function defaultFallbackText(interaction) {
  * 通过统一的 adapter.send 入口发送交互负载
  *
  * 通过 adapter.send(envelope, { kind: 'interaction', ... }) 发送交互。
- * 成功返回 'sent'，失败返回 false。
+ * 保留 adapter 的结构化回执，让调用方区分 sent、queued、failed 和
+ * suppressed；legacy adapter 的 void 返回表示已接受但尚无可验证回执。
  */
 export async function sendInteractionPayload(adapter, envelope, interaction, fallbackText, replyCtx) {
     const text = fallbackText ?? defaultFallbackText(interaction);
@@ -141,11 +148,11 @@ export async function sendInteractionPayload(adapter, envelope, interaction, fal
     try {
         const enriched = replyCtx ? withEnvelopeReplyContext(envelope, replyCtx) : envelope;
         const receipt = await adapter.send(enriched, payload);
-        if (receipt?.status === 'suppressed')
+        if (!receipt)
+            return LEGACY_INTERACTION_ACCEPTED;
+        if (receipt.status === 'sent' && !(receipt.messageId || receipt.messages[0]?.messageId))
             return false;
-        if (receipt?.status === 'sent')
-            return receipt.messages[0]?.messageId || false;
-        return 'sent';
+        return receipt;
     }
     catch {
         return false;