evolcore 0.0.11 → 0.0.13

package/dist/core/handoff/runtime.js

@@ -6,7 +6,9 @@ import { HandoffStore } from './store.js';
 import { createRootCausation, deriveCausation, normalizeCausation } from '../causation/context.js';
 import { recordCausationSpan } from '../causation/audit.js';
 import { logger } from '../../utils/logger.js';
+import { replyContextFromSession } from '../message/message-utils.js';
 const HANDOFF_STALE_WARN_MS = 72 * 60 * 60 * 1000;
+const HANDOFF_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 const HANDOFF_LARGE_AGGREGATE_COUNT = 10;
 const HANDOFF_LARGE_AGGREGATE_CHARS = 50_000;
 export class HandoffTargetBlockedError extends Error {
@@ -43,6 +45,15 @@ export class TriggerHandoffRequiredForbiddenError extends Error {
         this.name = 'TriggerHandoffRequiredForbiddenError';
     }
 }
+export class HandoffSessionReplacedError extends Error {
+    sessionId;
+    code = 'HANDOFF_SESSION_REPLACED';
+    constructor(sessionId) {
+        super(`handoff session was replaced during creation: ${sessionId}`);
+        this.sessionId = sessionId;
+        this.name = 'HandoffSessionReplacedError';
+    }
+}
 export class HandoffRuntime {
     sessionManager;
     messageQueue;
@@ -52,6 +63,8 @@ export class HandoffRuntime {
     now;
     staleWarned = new Set();
     largeAggregateWarned = new Set();
+    lifecycleSequence = 0;
+    sessionDiscardSequence = new Map();
     constructor(sessionManager, messageQueue, sender, store = new HandoffStore(), options = {}) {
         this.sessionManager = sessionManager;
         this.messageQueue = messageQueue;
@@ -60,13 +73,19 @@ export class HandoffRuntime {
         this.dispatcher = new HandoffDispatcher(store, this.mutexes, sender, options);
     }
     async createOutbound(input) {
+        const operationSequence = ++this.lifecycleSequence;
         throwIfAborted(input.signal);
         const origin = await this.sessionManager.getSessionById(input.originSessionId);
         throwIfAborted(input.signal);
         if (!origin || origin.selfAID !== input.selfAid)
             throw new Error('origin session not found');
         const targetChannelKey = formatChannelKey({ type: 'aun', selfAID: input.selfAid, name: 'main' });
-        const targetChatType = input.targetChatType ?? 'private';
+        if (!input.targetChatType) {
+            throw Object.assign(new Error('AUN handoff requires an explicit target chat type'), {
+                code: 'AUN_OUTBOUND_ROUTE_REQUIRED',
+            });
+        }
+        const targetChatType = input.targetChatType;
         const target = await this.sessionManager.getOrCreateSession(targetChannelKey, input.to, origin.projectPath, input.thread, {
             channelKey: targetChannelKey,
             peerId: input.to,
@@ -81,24 +100,32 @@ export class HandoffRuntime {
         if (input.explicitReturnPolicy === 'required' && input.causation?.trigger?.path.length) {
             throw new TriggerHandoffRequiredForbiddenError();
         }
-        await this.dispatcher.expireTargetQueued(input.selfAid, target.id);
-        throwIfAborted(input.signal);
-        const head = this.store.listByTarget(input.selfAid, target.id, 'queued')[0];
-        if (head?.attention_required) {
-            throw new HandoffTargetBlockedError(head.handoff_id, head.attention_reason ?? 'UNKNOWN_ATTENTION');
-        }
         const handoffCausation = deriveCausation(normalizeCausation(input.causation) ?? createRootCausation());
-        const handoff = this.store.create({
-            selfAid: input.selfAid,
-            originSessionId: origin.id,
-            originMessageId: input.originMessageId,
-            targetSessionId: target.id,
-            payload: input.payload,
-            encrypt: input.encrypt,
-            returnPolicy: input.explicitReturnPolicy ?? 'required',
-            originAuthorization: input.originAuthorization,
-            causation: handoffCausation,
-            now: this.now?.(),
+        const handoff = await this.mutexes.forKey(this.targetKey(input.selfAid, target.id)).runExclusive(async () => {
+            const replacedSessionId = [origin.id, target.id].find(sessionId => ((this.sessionDiscardSequence.get(this.sessionKey(input.selfAid, sessionId)) ?? 0) > operationSequence));
+            if (replacedSessionId)
+                throw new HandoffSessionReplacedError(replacedSessionId);
+            this.dispatcher.expireQueued(input.selfAid, target.id);
+            throwIfAborted(input.signal);
+            const head = this.store.listByTarget(input.selfAid, target.id, 'queued')[0];
+            if (head?.attention_required) {
+                throw new HandoffTargetBlockedError(head.handoff_id, head.attention_reason ?? 'UNKNOWN_ATTENTION');
+            }
+            return this.store.create({
+                selfAid: input.selfAid,
+                originSessionId: origin.id,
+                originMessageId: input.originMessageId,
+                targetSessionId: target.id,
+                payload: input.payload,
+                encrypt: input.encrypt,
+                delivery: targetChatType === 'group'
+                    ? { chatType: 'group', groupId: input.to }
+                    : { chatType: 'private' },
+                returnPolicy: input.explicitReturnPolicy ?? 'required',
+                originAuthorization: input.originAuthorization,
+                causation: handoffCausation,
+                now: this.now?.(),
+            });
         });
         recordCausationSpan(handoffCausation, 'handoff.request', {
             status: 'started',
@@ -106,6 +133,10 @@ export class HandoffRuntime {
         });
         await this.dispatcher.drain(input.selfAid, target.id);
         const dispatched = this.store.get(input.selfAid, handoff.handoff_id) ?? handoff;
+        const replacedSessionId = [origin.id, target.id].find(sessionId => ((this.sessionDiscardSequence.get(this.sessionKey(input.selfAid, sessionId)) ?? 0) > operationSequence));
+        if (dispatched.state === 'discarded' || replacedSessionId) {
+            throw new HandoffSessionReplacedError(replacedSessionId ?? target.id);
+        }
         if (dispatched.state === 'failed') {
             throw new HandoffDeliveryFailedError(dispatched.handoff_id);
         }
@@ -142,7 +173,9 @@ export class HandoffRuntime {
     }
     markBindingIncomplete(selfAid, handoffId) {
         const instance = this.store.get(selfAid, handoffId);
-        if (instance && !instance.attention_required) {
+        if (instance
+            && (instance.state === 'target_context_pending' || instance.state === 'return_pending')
+            && !instance.attention_required) {
             this.store.markAttention(selfAid, handoffId, 'REPLY_BINDING_INCOMPLETE');
         }
     }
@@ -185,6 +218,8 @@ export class HandoffRuntime {
             messageId,
             timestamp: Date.now(),
             source: 'handoff',
+            groupId: origin.chatType === 'group' ? (origin.metadata?.groupId || origin.channelId) : undefined,
+            replyContext: replyContextFromSession(origin),
             boundSessionId: origin.id,
             causation: instance.return_causation
                 ? deriveCausation(instance.return_causation)
@@ -207,16 +242,31 @@ export class HandoffRuntime {
                 role: origin.chatType === 'group' ? (origin.identity?.role ?? 'none') : undefined,
                 sessionKeyField: origin.sessionKey,
                 selfAID: origin.selfAID,
-                onPersisted: () => this.store.recordOriginEnqueued(selfAid, handoffId, messageId),
+                onPersisted: () => {
+                    if (this.store.get(selfAid, handoffId)?.state !== 'origin_queued') {
+                        throw new Error(`handoff is no longer deliverable: ${handoffId}`);
+                    }
+                    this.store.recordOriginEnqueued(selfAid, handoffId, messageId);
+                },
             });
         }
         catch (error) {
-            this.store.recordOriginEnqueueFailed(selfAid, handoffId, error instanceof Error ? error.message : String(error));
+            if (this.store.get(selfAid, handoffId)?.state === 'origin_queued') {
+                this.store.recordOriginEnqueueFailed(selfAid, handoffId, error instanceof Error ? error.message : String(error));
+            }
         }
     }
     buildPromptItem(message) {
         return this.buildPromptItems(message)[0] ?? null;
     }
+    isDiscardedDelivery(message) {
+        const delivery = message.handoffDelivery;
+        const selfAid = message.selfAID;
+        if (!delivery || !selfAid)
+            return false;
+        const ids = delivery.handoffIds?.length ? delivery.handoffIds : [delivery.handoffId];
+        return ids.length > 0 && ids.every(handoffId => this.store.get(selfAid, handoffId)?.state === 'discarded');
+    }
     buildPromptItems(message) {
         const delivery = message.handoffDelivery;
         const selfAid = message.selfAID;
@@ -367,9 +417,54 @@ export class HandoffRuntime {
             expired += this.dispatcher.expireQueued(selfAid).length;
         return expired;
     }
-    async recover(selfAids) {
+    async discardSession(selfAid, sessionId) {
+        this.sessionDiscardSequence.set(this.sessionKey(selfAid, sessionId), ++this.lifecycleSequence);
+        const candidates = this.store.list(selfAid)
+            .filter(instance => (instance.origin_session_id === sessionId || instance.target_session_id === sessionId) && instance.state !== 'failed' && instance.state !== 'completed' && instance.state !== 'discarded');
+        let discarded = 0;
+        for (const instance of candidates) {
+            const result = await this.discardWithTargetLock(selfAid, instance.handoff_id, 'session_replaced', {
+                session_id: sessionId,
+            });
+            if (result)
+                discarded++;
+        }
+        return discarded;
+    }
+    async discardExpired(selfAids, retentionMs = HANDOFF_RETENTION_MS) {
+        const now = this.now?.() ?? Date.now();
+        let discarded = 0;
+        for (const selfAid of selfAids) {
+            const latestEventVersions = new Map();
+            for (const event of this.store.events(selfAid)) {
+                if (!event.handoff_id || event.to_version === undefined)
+                    continue;
+                latestEventVersions.set(event.handoff_id, Math.max(latestEventVersions.get(event.handoff_id) ?? 0, event.to_version));
+            }
+            for (const instance of this.store.list(selfAid)) {
+                if (instance.state === 'failed' || instance.state === 'completed' || instance.state === 'discarded')
+                    continue;
+                if (now - instance.created_at <= retentionMs)
+                    continue;
+                if ((latestEventVersions.get(instance.handoff_id) ?? 0) !== instance.version)
+                    continue;
+                const result = await this.discardWithTargetLock(selfAid, instance.handoff_id, 'retention_expired', {
+                    retention_ms: retentionMs,
+                    age_ms: now - instance.created_at,
+                }, instance.version, now);
+                if (result) {
+                    discarded++;
+                    logger.info(`[Handoff] discarded expired handoff: ${instance.handoff_id}`);
+                }
+            }
+        }
+        return discarded;
+    }
+    async recover(selfAids, options = {}) {
         const originEnqueues = [];
         for (const selfAid of selfAids) {
+            if (options.discardExpired !== false)
+                await this.discardExpired([selfAid]);
             // v1 initially represented return=none as return_pending and required an
             // empty manual return. It has already been shown to a target turn, so
             // finish it before version reconciliation instead of prompting again.
@@ -412,6 +507,40 @@ export class HandoffRuntime {
         }
         await Promise.all(originEnqueues);
     }
+    async discardWithTargetLock(selfAid, handoffId, reason, details, expectedVersion, now = this.now?.()) {
+        const snapshot = this.store.get(selfAid, handoffId);
+        if (!snapshot)
+            return false;
+        const discarded = await this.mutexes.forKey(this.targetKey(selfAid, snapshot.target_session_id)).runExclusive(async () => {
+            const current = this.store.get(selfAid, handoffId);
+            if (!current || current.state === 'failed' || current.state === 'completed' || current.state === 'discarded') {
+                return null;
+            }
+            if (expectedVersion !== undefined && current.version !== expectedVersion)
+                return null;
+            this.store.discard(selfAid, handoffId, reason, details, now);
+            return current;
+        });
+        if (!discarded)
+            return false;
+        await this.cancelOriginDelivery(discarded);
+        return true;
+    }
+    async cancelOriginDelivery(instance) {
+        if (instance.state !== 'origin_queued' && instance.state !== 'origin_delivered')
+            return;
+        const messageId = instance.origin_delivery_message_id
+            ?? `origin-deliver:${instance.handoff_id}:${instance.origin_session_id}`;
+        const queue = this.messageQueue;
+        try {
+            const queued = queue.cancelMessageByIdInSession?.(instance.origin_session_id, messageId) ?? false;
+            if (!queued)
+                await queue.cancelActiveAndWait?.(messageId);
+        }
+        catch (error) {
+            logger.warn(`[Handoff] failed to cancel discarded origin delivery ${messageId}:`, error);
+        }
+    }
     warnIfStale(instance) {
         if (instance.state !== 'target_sent' && instance.state !== 'return_pending')
             return;
@@ -425,6 +554,12 @@ export class HandoffRuntime {
             + ` ageHours=${Math.floor(ageMs / 3_600_000)}`
             + ` originSession=${instance.origin_session_id} targetSession=${instance.target_session_id}`);
     }
+    targetKey(selfAid, targetSessionId) {
+        return `${selfAid}\u0000${targetSessionId}`;
+    }
+    sessionKey(selfAid, sessionId) {
+        return `${selfAid}\u0000${sessionId}`;
+    }
     warnIfLargeAggregate(message, instances, direction) {
         const chars = message.content.length
             + instances.reduce((total, instance) => total + this.requestSummary(instance).length, 0);

package/dist/core/handoff/store.js

@@ -9,6 +9,7 @@ import { HANDOFF_SCHEMA_VERSION, HANDOFF_QUERY_DEFAULT_LIMIT, HANDOFF_QUERY_MAX_
 import { normalizeCausation } from '../causation/context.js';
 const SAFE_ID_RE = /^[A-Za-z0-9._-]+$/;
 export const HANDOFF_ID_RE = /^h-[A-Za-z0-9._-]+$/;
+const TERMINAL_HANDOFF_STATES = new Set(['failed', 'completed', 'discarded']);
 function safeSegment(value, field) {
     if (!value || !SAFE_ID_RE.test(value) || value === '.' || value === '..') {
         throw new Error(`invalid ${field}`);
@@ -114,7 +115,11 @@ export class HandoffStore {
             origin_session_id: input.originSessionId,
             origin_message_id: input.originMessageId,
             target_session_id: input.targetSessionId,
-            request: { payload: clonePayload(input.payload), encrypt: input.encrypt },
+            request: {
+                payload: clonePayload(input.payload),
+                encrypt: input.encrypt,
+                ...(input.delivery ? { delivery: input.delivery } : {}),
+            },
             ...(input.originAuthorization
                 ? { origin_authorization: { ...input.originAuthorization } }
                 : {}),
@@ -514,6 +519,29 @@ export class HandoffStore {
         this.write(selfAid, instance);
         return instance;
     }
+    discard(selfAid, handoffId, reason, details = {}, now = Date.now()) {
+        const instance = this.get(selfAid, handoffId);
+        if (!instance)
+            throw new Error('handoff not found');
+        if (TERMINAL_HANDOFF_STATES.has(instance.state))
+            return instance;
+        const previousState = instance.state;
+        const previousVersion = instance.version;
+        instance.state = 'discarded';
+        instance.attention_required = false;
+        instance.attention_reason = null;
+        instance.version++;
+        instance.updated_at = now;
+        instance.completed_at = now;
+        this.appendEvent(selfAid, 'handoff_discarded', handoffId, {
+            fromVersion: previousVersion,
+            toVersion: instance.version,
+            details: { ...details, reason, previous_state: previousState },
+            now,
+        });
+        this.write(selfAid, instance);
+        return instance;
+    }
     requireState(selfAid, handoffId, expected) {
         const instance = this.get(selfAid, handoffId);
         if (!instance)

package/dist/core/handoff/types.js

@@ -8,6 +8,7 @@ export const HANDOFF_STATES = [
     'origin_queued',
     'origin_delivered',
     'completed',
+    'discarded',
 ];
 export const HANDOFF_QUERY_DEFAULT_LIMIT = 100;
 export const HANDOFF_QUERY_MAX_LIMIT = 500;

package/dist/core/interaction-router.js

@@ -228,6 +228,16 @@ export class InteractionRouter {
         return undefined;
     }
 }
+/** Bind an adapter response to its runtime-owned channel identity domain. */
+export function registerAdapterInteractions(adapter, router) {
+    const channelKey = adapter.channelKey;
+    adapter.onInteraction?.(async (response) => {
+        return router.handleAsync({ ...response, channelKey });
+    });
+    adapter.onInteractionInvalidated?.((interactionId, reason) => {
+        return router.cancelFromChannel(interactionId, reason);
+    });
+}
 /** 把 CommandCard 渲染为文本提示，channel 不支持卡片时使用 */
 export function renderCommandCardAsText(card) {
     const lines = [card.title];

package/dist/core/message/im-renderer.js

@@ -244,6 +244,25 @@ export class IMRenderer {
             durationMs: opts.durationMs,
         });
     }
+    /** 发送不进入 activity/thought 历史的非终态 warning status。 */
+    async sendWarningStatus(message, subtype, details) {
+        const payload = {
+            kind: 'status.progress',
+            metadata: {
+                activityType: 'progress',
+                message,
+                severity: 'warn',
+                ...(subtype !== undefined && { subtype }),
+                ...(details?.missingItems !== undefined && { missingItems: details.missingItems }),
+            },
+        };
+        try {
+            await this.opts.send(payload);
+        }
+        catch (error) {
+            logger.warn(`[IMRenderer] warning status send failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     /** 添加任务生命周期边界事件，复用 activity.batch 投影路径。 */
     addLifecycle(phase, metadata, text) {
         const item = {

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

@@ -110,6 +110,7 @@ export class LogicalQueueBridge {
             peerId: message.peerId,
             content: message.content,
             chatType: message.chatType ?? 'private',
+            mentions: message.mentions,
             isMentioned: message.isMentioned,
             mentionAids: message.mentionAids,
         };

package/dist/core/message/mention-schema.js

@@ -0,0 +1,126 @@
+export class MentionSchemaError extends Error {
+    code = 'INVALID_MENTION_SCHEMA';
+    index;
+    constructor(message, index) {
+        super(index === undefined ? message : `mentions[${index}]: ${message}`);
+        this.name = 'MentionSchemaError';
+        this.index = index;
+    }
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function assertMetadata(value, index) {
+    if (hasOwn(value, 'display') && typeof value.display !== 'string') {
+        throw new MentionSchemaError('display must be a string', index);
+    }
+    for (const key of ['offset', 'length']) {
+        if (!hasOwn(value, key))
+            continue;
+        const field = value[key];
+        if (typeof field !== 'number' || !Number.isInteger(field) || field < 0) {
+            throw new MentionSchemaError(`${key} must be a non-negative integer`, index);
+        }
+    }
+    for (const key of ['name', 'key']) {
+        if (hasOwn(value, key) && typeof value[key] !== 'string') {
+            throw new MentionSchemaError(`${key} must be a string`, index);
+        }
+    }
+}
+/**
+ * Validate and copy canonical mention entries.
+ *
+ * This is intentionally strict: the old string array format is rejected
+ * instead of being converted, because conversion can hide a producer bug and
+ * make routing appear to work with the wrong wire contract.
+ */
+export function normalizeMentionEntries(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new MentionSchemaError('mentions must be an array');
+    }
+    const normalized = [];
+    for (const [index, value] of raw.entries()) {
+        if (typeof value === 'string') {
+            throw new MentionSchemaError('legacy string entries are not supported; use {aid} or {scope:"all"}', index);
+        }
+        if (!isRecord(value)) {
+            throw new MentionSchemaError('entry must be an object', index);
+        }
+        const hasScope = hasOwn(value, 'scope');
+        const hasAid = hasOwn(value, 'aid');
+        const hasUserId = hasOwn(value, 'userId');
+        const discriminatorCount = Number(hasScope) + Number(hasAid) + Number(hasUserId);
+        if (discriminatorCount !== 1) {
+            throw new MentionSchemaError('entry must contain exactly one of scope, aid, or userId', index);
+        }
+        assertMetadata(value, index);
+        if (hasScope) {
+            if (value.scope !== 'all') {
+                throw new MentionSchemaError('scope must be "all"', index);
+            }
+            normalized.push({ ...value, scope: 'all' });
+            continue;
+        }
+        if (hasAid) {
+            if (typeof value.aid !== 'string' || value.aid.length === 0 || value.aid.trim() !== value.aid) {
+                throw new MentionSchemaError('aid must be a non-empty trimmed string', index);
+            }
+            if (value.aid === 'all') {
+                throw new MentionSchemaError('all is a scope, not an aid; use {scope:"all"}', index);
+            }
+            normalized.push({ ...value, aid: value.aid });
+            continue;
+        }
+        if (typeof value.userId !== 'string' || value.userId.length === 0 || value.userId.trim() !== value.userId) {
+            throw new MentionSchemaError('userId must be a non-empty trimmed string', index);
+        }
+        if (value.userId === 'all') {
+            throw new MentionSchemaError('all is a scope, not a userId; use {scope:"all"}', index);
+        }
+        normalized.push({ ...value, userId: value.userId });
+    }
+    return normalized;
+}
+export function mentionEntryIsAll(entry) {
+    return 'scope' in entry && entry.scope === 'all';
+}
+/** Return all concrete target IDs, including channel-native userId entries. */
+export function mentionEntryTargets(entries) {
+    const targets = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        const target = 'aid' in entry && typeof entry.aid === 'string'
+            ? entry.aid
+            : 'userId' in entry && typeof entry.userId === 'string'
+                ? entry.userId
+                : undefined;
+        if (!target || target === 'all' || seen.has(target))
+            continue;
+        seen.add(target);
+        targets.push(target);
+    }
+    return targets;
+}
+export function hasMentionAll(entries) {
+    return entries.some(mentionEntryIsAll);
+}
+/** IDs used by renderers; keeps `all` visible as a derived value. */
+export function mentionEntryAids(entries) {
+    const aids = mentionEntryTargets(entries);
+    if (hasMentionAll(entries))
+        aids.push('all');
+    return aids;
+}
+export function mentionEntryKey(entry) {
+    if ('scope' in entry && entry.scope === 'all')
+        return 'scope:all';
+    if ('aid' in entry)
+        return `aid:${entry.aid}`;
+    return `user:${entry.userId}`;
+}