evolcore 0.0.21 → 0.0.23

package/dist/channels/aun.js

@@ -34,7 +34,8 @@ import { deriveCausation, normalizeCausation } from '../core/causation/context.j
 import { recordCausationSpan } from '../core/causation/audit.js';
 import { refreshAgentDisplayName, resolveAgentDisplayName } from '../aun/aid/agentmd.js';
 import { readInstalledEvolcoreVersion } from '../utils/evolcore-version.js';
-import { bindPostBootstrapWelcomeOutboxSession, hasPendingPostBootstrapWelcomeOutbox, bootstrapInitialMessageOperationId, postBootstrapWelcomeOperationId, preparePostBootstrapWelcomeOutbox, } from '../core/bootstrap-messages.js';
+import { toolInputForDisplay } from '../utils/tool-summary.js';
+import { bindPostBootstrapWelcomeOutboxSession, hasPendingPostBootstrapWelcomeOutbox, bootstrapInitialMessageOperationPrefix, postBootstrapWelcomeOperationId, preparePostBootstrapWelcomeOutbox, } from '../core/bootstrap-messages.js';
 import { hasMentionAll, mentionEntryAids, mentionEntryTargets, } from '../core/message/mention-schema.js';
 import { normalizeAunMentionEntries, } from '../aun/msg/mention-schema.js';
 import { isDeliveryTarget, sameDeliveryTarget } from '../core/message/message-utils.js';
@@ -45,6 +46,9 @@ const AUN_INBOUND_DEDUP_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const IMAGE_MIME_TYPE = /^image\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$/i;
 const AUN_ATTACHMENT_DOWNLOAD_ATTEMPTS = 3;
 const AUN_ATTACHMENT_RETRY_DELAYS_MS = [250, 750];
+const OBSERVER_GROUP_MEMBERS_TTL_MS = 60_000;
+const OBSERVER_GROUP_MEMBERS_PAGE_SIZE = 200;
+const OBSERVER_GROUP_MEMBERS_MAX_PAGES = 100;
 const AUN_SEND_LOG_TEXT_MAX_LENGTH = 60;
 export function formatAunSendLogText(text) {
     return text.replace(/\s+/gu, ' ').trim().slice(0, AUN_SEND_LOG_TEXT_MAX_LENGTH);
@@ -480,7 +484,8 @@ function redactMenuTokensForTrace(value, seen = new WeakSet()) {
         return value.map(item => redactMenuTokensForTrace(item, seen));
     const redacted = {};
     for (const [key, item] of Object.entries(value)) {
-        redacted[key] = key.toLowerCase() === 'menu_token'
+        const normalizedKey = key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/-/g, '_').toLowerCase();
+        redacted[key] = /^(?:menu|ecweb)_token$/.test(normalizedKey)
             ? '[REDACTED]'
             : redactMenuTokensForTrace(item, seen);
     }
@@ -1062,6 +1067,18 @@ export class AUNChannel {
             .replace(/[ \t]+/g, ' ')
             .trim();
     }
+    /** Normalize a command after a client-rendered friendly mention label. */
+    normalizeSlashCommandText(text) {
+        const trimmed = text.trim();
+        const leadingLabels = trimmed.match(/^(?:@[^\s]+\s+)+(?=\/)/u);
+        const commandText = leadingLabels
+            ? trimmed.slice(leadingLabels[0].length).trimStart()
+            : trimmed;
+        // Keep the command contract consistent for mixed friendly/canonical @
+        // tokens: selector labels are removed above, then known AID-shaped tokens
+        // anywhere in the command are removed by the existing helper.
+        return this.stripAllMentions(commandText);
+    }
     parsePayloadMentionsOrReject(payload, context, messageId, seq) {
         const raw = payload && typeof payload === 'object' && !Array.isArray(payload)
             ? payload.mentions
@@ -1277,6 +1294,8 @@ export class AUNChannel {
     /** 撤权可能先于 outbox 卡片投递完成；迟到卡片注册后立即撤回。 */
     invalidatedInteractions = new Map();
     mentionModeResolver;
+    /** Agent-level policy controlling whether group slash commands require structured mentions. */
+    groupSlashRequireMentionsResolver;
     static PROACTIVE_ALLOW_TYPES = new Set([
         'text', 'quote', 'image', 'video', 'voice', 'file', 'json',
         'merge', 'link', 'location', 'personal_card',
@@ -1401,6 +1420,14 @@ export class AUNChannel {
         }
     }
     async _initClientInner() {
+        this.observerGroupMembers.clear();
+        for (const groupId of new Set([
+            ...this.observerGroupMembershipEpoch.keys(),
+            ...this.observerGroupMemberFetches.keys(),
+        ])) {
+            this.observerGroupMembershipEpoch.set(groupId, (this.observerGroupMembershipEpoch.get(groupId) ?? 0) + 1);
+        }
+        this.observerGroupMemberFetches.clear();
         // Clean up existing client if any
         if (this.client) {
             this.trace('OUT', 'client.close', { reason: 'initClient' });
@@ -1469,6 +1496,44 @@ export class AUNChannel {
                 logger.debug(`${this.logPrefix()}[DIAG] group.message_created: group_id=${gid} sender=${sender}`);
                 this.handleIncomingGroupMessage(data);
             });
+            client.on('group.changed', (data) => {
+                if (!isCurrentClient())
+                    return;
+                const record = data && typeof data === 'object' ? data : {};
+                const envelope = record.envelope && typeof record.envelope === 'object'
+                    ? record.envelope
+                    : {};
+                this.invalidateObserverGroupMembers(envelope.group_id ?? record.group_id);
+            });
+            // fastaun 0.5.12+ exposes targeted invitations as a local, aggregated
+            // event. It is a control signal, not a user message, so keep it out of
+            // the Agent routing path while retaining it in diagnostics.
+            client.on('group.invite_received', (data) => {
+                if (!isCurrentClient())
+                    return;
+                const record = data && typeof data === 'object' ? data : {};
+                const groupId = record.group_id ?? record.group_aid ?? 'unknown';
+                const inviteIds = Array.isArray(record.invite_ids) ? record.invite_ids : [];
+                this.trace('IN', 'group.invite_received', data);
+                logger.info(`${this.logPrefix()} Group invitation received: group=${groupId} pending=${inviteIds.length || 1}`);
+            });
+        }
+        // 0.5.10/0.5.11 local lifecycle events summarize SDK delivery and Pull
+        // progress. They must never be interpreted as inbound chat messages.
+        for (const eventName of ['delivery.changed', 'sync.started', 'sync.progress', 'sync.stopped']) {
+            client.on(eventName, (data) => {
+                if (!isCurrentClient())
+                    return;
+                this.trace('IN', eventName, data);
+                if (eventName === 'sync.progress') {
+                    const record = data && typeof data === 'object' ? data : {};
+                    logger.debug(`${this.logPrefix()} AUN sync progress: namespace=${record.namespace ?? 'unknown'} page=${record.page ?? '?'} pulled=${record.page_pulled_count ?? record.pulled_count ?? 0}`);
+                }
+                else if (eventName === 'sync.stopped') {
+                    const record = data && typeof data === 'object' ? data : {};
+                    logger.info(`${this.logPrefix()} AUN sync stopped: reason=${record.reason ?? 'unknown'}`);
+                }
+            });
         }
         const handleSdkState = (source) => (data) => {
             if (!isCurrentClient())
@@ -2034,7 +2099,7 @@ export class AUNChannel {
         // 显式排除 observer.inject：它是 owner 对本 agent 的控制消息，不应镜像给观察者
         // （即便日后 from-owner 排除规则调整，也不会泄漏）。
         if (inboundType !== AUNChannel.INJECT_REQUEST_TYPE) {
-            this.forwardInbound(msg);
+            void this.forwardInbound(msg);
         }
         // 回声过滤：自己发出的消息会被 gateway fanout 回来，
         // 只有 from_aid == self 且 chat_id 不匹配时才丢弃（说明是其它实例发的）
@@ -2205,7 +2270,7 @@ export class AUNChannel {
         }
         // Observer forward (inbound)：群聊消息在所有过滤之前转发原始明文 payload。
         // forwardInbound 内部排除 self-echo 与 from-owner。
-        this.forwardInbound(msg);
+        void this.forwardInbound(msg);
         logger.debug(`${this.logPrefix()}[DIAG-GRP] full_msg=${JSON.stringify(msg).substring(0, 500)}`);
         if (!groupId || !senderAid) {
             this.acknowledgeImmediately(messageId, seq);
@@ -2316,9 +2381,13 @@ export class AUNChannel {
         const firstLineGroup = text.split('\n')[0] || '';
         const hasEvolCoreTraceGroup = /\[EvolCore\.(receive|reply|agent)\]/.test(text);
         const isEchoMsg = /echo/i.test(firstLineGroup) && !hasEvolCoreTraceGroup;
+        const slashCommandText = this.normalizeSlashCommandText(text);
         // 命令判定：剥离所有 @ 后看是否 / 开头（多 @ 场景如 @a @b /status 也能正确识别）。
         // echo 消息走独立的 trace 流程，不参与命令语义判定。
-        const isCommandMsg = !isEchoMsg && this.stripAllMentions(text).startsWith('/');
+        const isCommandMsg = !isEchoMsg && slashCommandText.startsWith('/');
+        const groupSlashRequireMentions = this.groupSlashRequireMentionsResolver
+            ? await this.groupSlashRequireMentionsResolver().catch(() => undefined) ?? true
+            : true;
         if (isEchoMsg) {
             // 短 echo（≤10 字符）已在前面的快速通道命中并 return，这里只处理长 echo
             // >10 字符：追加 trace,存 pending echo,跳过 mention 过滤继续走 Agent 流程
@@ -2345,9 +2414,10 @@ export class AUNChannel {
         }
         else {
             // 非 echo 消息：mention 标记（不再过滤，交给响应模式决定）
-            // slash 命令在任何 mentionMode 下都强制走 mention-only 语义
-            // 即必须 @ 本 agent（或 @all）才处理，避免广播群里一条命令被全部 agent 各自执行。
-            const enforceMention = mentionMode === 'mention-only' || isCommandMsg;
+            // slash 命令默认要求结构化 @；Agent 可通过
+            // groupSlashRequireMentions=false 选择仅按正文命令格式处理。
+            const enforceMention = (mentionMode === 'mention-only' && !isCommandMsg)
+                || (isCommandMsg && groupSlashRequireMentions);
             const isMentioned = mentionedSelf || mentionedAll;
             // 过滤逻辑下移到响应层：这里只标记，不过滤
             // 但为了保持现有行为兼容（避免大量未 @ 消息涌入），暂时保留过滤
@@ -2355,14 +2425,14 @@ export class AUNChannel {
             if (enforceMention && !isMentioned && !isOwnHandoff) {
                 this.acknowledgeImmediately(messageId, seq);
                 this.appendInboundPayloadJsonl(groupId, senderAid, messageId, msgEncrypted, true, logDescriptor, threadId, receivedAt, seq);
-                logger.info(`${this.logPrefix()} Group dropped: unmentioned (group=${groupId} sender=${senderAid} mid=${messageId} mentionMode=${mentionMode} isCommand=${isCommandMsg} textPreview=${JSON.stringify(text.slice(0, 80))})`);
+                logger.info(`${this.logPrefix()} Group dropped: unmentioned (group=${groupId} sender=${senderAid} mid=${messageId} mentionMode=${mentionMode} slashRequireMentions=${groupSlashRequireMentions} isCommand=${isCommandMsg} textPreview=${JSON.stringify(text.slice(0, 80))})`);
                 return;
             }
         }
         // 命令消息：剥离所有 @（多 agent 被 @ 时各自拿到干净的 /status 各自执行）；
         // 普通消息：仅在唯一 @ 是自己时剥离，保留其他 @ 供 agent 感知。
         const strippedText = isCommandMsg
-            ? this.stripAllMentions(text)
+            ? slashCommandText
             : this.stripSelfMentionIfOnly(text, this._aid);
         // Detect attachments before the empty-text guard (顶层 + 嵌套)
         const rawAttachments = this.collectAllAttachments(payload);
@@ -2393,7 +2463,7 @@ export class AUNChannel {
                 : mentionedSelf
                     ? (structMentionSelf ? 'mention.self(struct)' : 'mention.self(text)')
                     : `${mentionMode}.no-mention`;
-        logger.info(`${this.logPrefix()} Group mention decision: mid=${messageId} group=${groupId} sender=${shortAid}(${displayName}) peerType=${peerIdentity.type} payloadType=${payloadType} mentionMode=${mentionMode} reason=${reason} structMentions=${JSON.stringify(payloadMentionEntries)} textMentionSelf=${textMentionSelf} textMentionAll=${textMentionAll} structMentionSelf=${structMentionSelf} structMentionAll=${structMentionAll} encrypt=${msgEncrypted} textPreview=${JSON.stringify(text.slice(0, 80))}`);
+        logger.info(`${this.logPrefix()} Group mention decision: mid=${messageId} group=${groupId} sender=${shortAid}(${displayName}) peerType=${peerIdentity.type} payloadType=${payloadType} mentionMode=${mentionMode} slashRequireMentions=${groupSlashRequireMentions} reason=${reason} structMentions=${JSON.stringify(payloadMentionEntries)} textMentionSelf=${textMentionSelf} textMentionAll=${textMentionAll} structMentionSelf=${structMentionSelf} structMentionAll=${structMentionAll} encrypt=${msgEncrypted} textPreview=${JSON.stringify(text.slice(0, 80))}`);
         // action_card_reply 已在 extractTextPayload 中消费，不分发给 agent
         if (payloadType === 'action_card_reply')
             return;
@@ -2564,6 +2634,9 @@ export class AUNChannel {
     // observable / owners 不在此处缓存——由 daemon 注入 resolver，从 EvolAgent 的
     // in-memory merged config（启动/重启/热重载时统一更新的唯一缓存）读取，避免重复缓存。
     observerConfigResolver;
+    observerGroupMembers = new Map();
+    observerGroupMemberFetches = new Map();
+    observerGroupMembershipEpoch = new Map();
     /** 注入观察者配置读取器（daemon 侧从 EvolAgent merged config 读）。 */
     setObserverConfigResolver(fn) {
         this.observerConfigResolver = fn;
@@ -2582,23 +2655,129 @@ export class AUNChannel {
      * data 为 SDK message.received / group.message_created 回调的整个对象，
      * 不拆解、不重组——SDK 信封结构变化不影响此处。
      */
+    async resolveObserverGroupMembers(groupId) {
+        if (!groupId || !this.client)
+            return undefined;
+        const cached = this.observerGroupMembers.get(groupId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.aids;
+        const pending = this.observerGroupMemberFetches.get(groupId);
+        if (pending)
+            return pending;
+        const epoch = this.observerGroupMembershipEpoch.get(groupId) ?? 0;
+        let request;
+        request = (async () => {
+            try {
+                const result = await this.callAndTrace('group.get_members', {
+                    group_id: groupId,
+                    page: 1,
+                    size: OBSERVER_GROUP_MEMBERS_PAGE_SIZE,
+                });
+                const rawMembers = Array.isArray(result?.members)
+                    ? result.members
+                    : Array.isArray(result?.items) ? result.items : undefined;
+                if (!rawMembers)
+                    return undefined;
+                const hasTotal = Number.isFinite(Number(result?.total));
+                const hasMore = result?.has_more === true || result?.hasMore === true;
+                if (!hasTotal && (hasMore || rawMembers.length >= OBSERVER_GROUP_MEMBERS_PAGE_SIZE))
+                    return undefined;
+                const allMembers = [...rawMembers];
+                const total = Number(result?.total);
+                const pageSize = Number(result?.size) > 0 ? Number(result.size) : OBSERVER_GROUP_MEMBERS_PAGE_SIZE;
+                const pageCount = Number.isFinite(total) && total > allMembers.length
+                    ? Math.ceil(total / pageSize)
+                    : 1;
+                if (pageCount > OBSERVER_GROUP_MEMBERS_MAX_PAGES)
+                    return undefined;
+                for (let page = 2; page <= pageCount; page++) {
+                    const next = await this.callAndTrace('group.get_members', {
+                        group_id: groupId,
+                        page,
+                        size: OBSERVER_GROUP_MEMBERS_PAGE_SIZE,
+                    });
+                    const nextMembers = Array.isArray(next?.members)
+                        ? next.members
+                        : Array.isArray(next?.items) ? next.items : undefined;
+                    if (!nextMembers)
+                        return undefined;
+                    allMembers.push(...nextMembers);
+                }
+                if (hasTotal && total > allMembers.length)
+                    return undefined;
+                const aids = new Set();
+                for (const member of allMembers) {
+                    const aid = typeof member === 'string'
+                        ? member.trim()
+                        : typeof member?.aid === 'string' ? member.aid.trim()
+                            : typeof member?.member_aid === 'string' ? member.member_aid.trim() : '';
+                    if (aid)
+                        aids.add(aid);
+                }
+                if ((this.observerGroupMembershipEpoch.get(groupId) ?? 0) === epoch) {
+                    this.observerGroupMembers.set(groupId, { aids, expiresAt: Date.now() + OBSERVER_GROUP_MEMBERS_TTL_MS });
+                }
+                return aids;
+            }
+            catch (error) {
+                logger.debug(`${this.logPrefix()} observer group membership lookup failed group=${groupId}: ${error}`);
+                return undefined;
+            }
+            finally {
+                if (this.observerGroupMemberFetches.get(groupId) === request) {
+                    this.observerGroupMemberFetches.delete(groupId);
+                }
+            }
+        })();
+        this.observerGroupMemberFetches.set(groupId, request);
+        return request;
+    }
+    invalidateObserverGroupMembers(groupId) {
+        if (typeof groupId !== 'string' || !groupId.trim())
+            return;
+        const key = groupId.trim();
+        this.observerGroupMembers.delete(key);
+        this.observerGroupMembershipEpoch.set(key, (this.observerGroupMembershipEpoch.get(key) ?? 0) + 1);
+    }
+    async observerRecipients(owners, envelope) {
+        if (owners.length === 0)
+            return owners;
+        const groupId = typeof envelope.group_id === 'string' ? envelope.group_id.trim() : '';
+        const members = groupId ? await this.resolveObserverGroupMembers(groupId) : undefined;
+        // Unknown membership is fail-open for observation: only an explicit member
+        // response may suppress the redundant owner DM.
+        return owners.filter(owner => !(members?.has(owner)));
+    }
     forwardInbound(data) {
         if (!this.connected || !this.client)
-            return;
+            return Promise.resolve();
         if (payloadTypeForObserver(data)?.startsWith('menu.'))
-            return;
+            return Promise.resolve();
         const { observable, owners } = this.getObserverConfig();
         if (!observable || owners.length === 0)
-            return;
-        const env = (data?.envelope && typeof data.envelope === 'object') ? data.envelope : {};
+            return Promise.resolve();
+        const env = (data?.envelope && typeof data.envelope === 'object')
+            ? { ...data.envelope }
+            : {};
+        if (!env.group_id && typeof data.group_id === 'string')
+            env.group_id = data.group_id;
         const from = env.from ?? '';
         if (this._aid && from === this._aid)
-            return; // self-echo：已在出站转过
+            return Promise.resolve(); // self-echo：已在出站转过
         // 排除来源 owner（不把"owner A 发来的"再转回 A），但仍转给其他 owner。
-        const recipientOwners = owners.filter(o => o !== from);
-        if (recipientOwners.length === 0)
-            return;
-        this.emitForward('inbound', data, recipientOwners);
+        const candidateOwners = owners.filter(o => o !== from);
+        if (candidateOwners.length === 0)
+            return Promise.resolve();
+        if (typeof env.group_id !== 'string' || !env.group_id.trim()) {
+            this.emitForward('inbound', data, candidateOwners);
+            return Promise.resolve();
+        }
+        return this.observerRecipients(candidateOwners, env)
+            .then(recipientOwners => {
+            if (recipientOwners.length > 0)
+                this.emitForward('inbound', data, recipientOwners);
+        })
+            .catch(error => logger.debug(`${this.logPrefix()} observer inbound recipient lookup failed: ${error}`));
     }
     /**
      * 出站转发：Agent 经 AUN 真实发出的消息原样转发给 owner。
@@ -2607,20 +2786,33 @@ export class AUNChannel {
      */
     forwardOutbound(result) {
         if (!this.connected || !this.client)
-            return;
+            return Promise.resolve();
         if (payloadTypeForObserver(result)?.startsWith('menu.'))
-            return;
+            return Promise.resolve();
         const { observable, owners } = this.getObserverConfig();
         if (!observable || owners.length === 0)
-            return;
-        const env = (result?.envelope && typeof result.envelope === 'object') ? result.envelope : {};
+            return Promise.resolve();
+        const env = (result?.envelope && typeof result.envelope === 'object')
+            ? { ...result.envelope }
+            : {};
+        if (!env.group_id && typeof result.group_id === 'string')
+            env.group_id = result.group_id;
         const to = env.to ?? env.group_id ?? '';
         // 过滤：若对端本身是 owner，不转发给该 owner（避免"回复你"转给你自己）；
         // 但仍转发给其他 owner。
-        const recipientOwners = owners.filter(o => o !== to);
-        if (recipientOwners.length === 0)
-            return;
-        this.emitForward('outbound', result, recipientOwners);
+        const candidateOwners = owners.filter(o => o !== to);
+        if (candidateOwners.length === 0)
+            return Promise.resolve();
+        if (typeof env.group_id !== 'string' || !env.group_id.trim()) {
+            this.emitForward('outbound', result, candidateOwners);
+            return Promise.resolve();
+        }
+        return this.observerRecipients(candidateOwners, env)
+            .then(recipientOwners => {
+            if (recipientOwners.length > 0)
+                this.emitForward('outbound', result, recipientOwners);
+        })
+            .catch(error => logger.debug(`${this.logPrefix()} observer outbound recipient lookup failed: ${error}`));
     }
     /**
      * 实际投递 observer.forward 给每个 owner，使用 daemon 的全局 AUN 默认加密设置。
@@ -3104,6 +3296,9 @@ export class AUNChannel {
     setMentionModeResolver(resolver) {
         this.mentionModeResolver = resolver;
     }
+    setGroupSlashRequireMentionsResolver(resolver) {
+        this.groupSlashRequireMentionsResolver = resolver;
+    }
     onRecall(handler) {
         this.recallHandler = handler;
     }
@@ -3711,9 +3906,15 @@ export class AUNChannel {
         return truncated;
     }
     buildActivityPayload(envelope, context, item) {
-        const activityItem = item && typeof item === 'object' && !Array.isArray(item)
+        const rawItem = item && typeof item === 'object' && !Array.isArray(item)
             ? { ...item }
             : { kind: 'unknown', text: String(item ?? '') };
+        const displayArguments = rawItem.kind === 'tool_call'
+            ? toolInputForDisplay(rawItem.name, rawItem.arguments)
+            : undefined;
+        const activityItem = rawItem.kind === 'tool_call' && displayArguments !== rawItem.arguments
+            ? { ...rawItem, arguments: displayArguments }
+            : rawItem;
         return {
             ...this.buildTaskPayloadBase(envelope, context),
             type: 'activity',
@@ -5119,13 +5320,11 @@ export class AUNChannel {
         const owner = getFirstStaticAgentOwner(aid);
         if (!owner)
             return;
-        const operationIds = new Set([
-            bootstrapInitialMessageOperationId(aid),
-            postBootstrapWelcomeOperationId(aid),
-        ]);
-        const entries = [...operationIds]
-            .map(operationId => outbox.findByDedupeKey(aid, operationId, { includeTerminal: true }))
-            .filter((entry) => !!entry?.channelId);
+        const completionEntry = outbox.findByDedupeKey(aid, postBootstrapWelcomeOperationId(aid), { includeTerminal: true });
+        const entries = [
+            ...outbox.findByDedupePrefix(aid, bootstrapInitialMessageOperationPrefix(aid), { includeTerminal: true }),
+            ...(completionEntry ? [completionEntry] : []),
+        ].filter((entry) => !!entry?.channelId);
         for (const entry of entries) {
             const delivery = { chatType: 'private' };
             const nestedDelivery = entry.context?.delivery;
@@ -5915,6 +6114,11 @@ export class AUNChannelPlugin {
                         }, { cache: true }).mentionMode;
                     });
                 }
+                if (typeof channel.setGroupSlashRequireMentionsResolver === 'function') {
+                    channel.setGroupSlashRequireMentionsResolver(async () => {
+                        return resolveEffective({ self: aid }, { cache: true }).groupSlashRequireMentions ?? true;
+                    });
+                }
             },
         };
     }

package/dist/channels/wechat.js

@@ -40,6 +40,8 @@ const BACKOFF_DELAY_MS = 30_000;
 const RETRY_DELAY_MS = 2_000;
 const TYPING_TICKET_TTL_MS = 5 * 60 * 1000; // 5 min cache
 const SESSION_EXPIRED_ERRCODE = -14;
+const INVALID_SYNC_CURSOR_ERRCODE = -1;
+const MAX_SYNC_CURSOR_BYTES = 64 * 1024;
 export class WechatApiError extends Error {
     endpoint;
     ret;
@@ -71,6 +73,26 @@ export class WechatContextTokenRefreshRequiredError extends Error {
         }
     }
 }
+/**
+ * iLink cursors are opaque text, so validation deliberately stays conservative:
+ * reject values that cannot be safely round-tripped through the UTF-8 state file
+ * without imposing a specific encoding on future protocol versions.
+ */
+export function validateWechatSyncCursor(cursor) {
+    if (typeof cursor !== 'string') {
+        return { valid: false, reason: 'invalid_type' };
+    }
+    if (Buffer.byteLength(cursor, 'utf8') > MAX_SYNC_CURSOR_BYTES) {
+        return { valid: false, reason: 'too_large' };
+    }
+    if (cursor.includes('\uFFFD')) {
+        return { valid: false, reason: 'invalid_utf8' };
+    }
+    if (/[\s\u0000-\u001F\u007F-\u009F]/u.test(cursor)) {
+        return { valid: false, reason: 'invalid_character' };
+    }
+    return { valid: true };
+}
 /** Classify fetch/undici failures using the categories exposed by Tencent 2.4.6. */
 export function classifyFetchError(err) {
     if (err instanceof Error && err.name === 'AbortError') {
@@ -196,6 +218,7 @@ export class WechatChannel {
     pendingContextMessages = new Map();
     typingTicketCache = new Map();
     getUpdatesBuf = '';
+    lastRejectedSyncCursor;
     syncBufPath;
     contextTokensPath;
     onSessionExpired;
@@ -243,14 +266,24 @@ export class WechatChannel {
             throw new Error('WeChat reauthentication required; run: ec init wechat');
         }
         // 恢复游标
+        this.getUpdatesBuf = '';
+        this.lastRejectedSyncCursor = undefined;
         try {
             if (fs.existsSync(this.syncBufPath)) {
-                this.getUpdatesBuf = fs.readFileSync(this.syncBufPath, 'utf-8');
-                logger.info(`[WeChat] Restored sync cursor (${this.getUpdatesBuf.length} bytes)`);
+                const restoredCursor = fs.readFileSync(this.syncBufPath, 'utf-8');
+                const validation = validateWechatSyncCursor(restoredCursor);
+                if (validation.valid) {
+                    this.getUpdatesBuf = restoredCursor;
+                    logger.info(`[WeChat] Restored sync cursor (${Buffer.byteLength(restoredCursor, 'utf8')} bytes)`);
+                }
+                else {
+                    this.clearSyncCursor(`persisted cursor is invalid (${validation.reason})`, restoredCursor);
+                }
             }
         }
-        catch {
-            // ignore
+        catch (err) {
+            logger.warn(`[WeChat] Failed to restore sync cursor; starting from an empty cursor: ${err instanceof Error ? err.message : String(err)}`);
+            this.getUpdatesBuf = '';
         }
         // 通知 ilink 后端：bot 上线
         try {
@@ -431,13 +464,22 @@ export class WechatChannel {
                 }
                 consecutiveFailures = 0;
                 // 保存游标
-                if (resp.get_updates_buf) {
-                    this.getUpdatesBuf = resp.get_updates_buf;
-                    try {
-                        fs.writeFileSync(this.syncBufPath, this.getUpdatesBuf, 'utf-8');
+                if (resp.get_updates_buf !== undefined) {
+                    const validation = validateWechatSyncCursor(resp.get_updates_buf);
+                    if (!validation.valid) {
+                        this.clearSyncCursor(`server returned an invalid cursor (${validation.reason})`, typeof resp.get_updates_buf === 'string' ? resp.get_updates_buf : undefined);
                     }
-                    catch {
-                        // best-effort
+                    else if (resp.get_updates_buf) {
+                        if (resp.get_updates_buf !== this.lastRejectedSyncCursor) {
+                            this.lastRejectedSyncCursor = undefined;
+                        }
+                        this.getUpdatesBuf = resp.get_updates_buf;
+                        try {
+                            fs.writeFileSync(this.syncBufPath, this.getUpdatesBuf, 'utf-8');
+                        }
+                        catch {
+                            // best-effort
+                        }
                     }
                 }
                 // 处理消息
@@ -450,6 +492,17 @@ export class WechatChannel {
                     return;
                 if (this.isSessionPaused())
                     return;
+                if (err instanceof WechatApiError &&
+                    err.endpoint === 'ilink/bot/getupdates' &&
+                    err.hasCode(INVALID_SYNC_CURSOR_ERRCODE) &&
+                    this.getUpdatesBuf &&
+                    this.getUpdatesBuf !== this.lastRejectedSyncCursor) {
+                    const rejectedCursor = this.getUpdatesBuf;
+                    this.clearSyncCursor('getUpdates returned ret=-1', rejectedCursor);
+                    consecutiveFailures = 0;
+                    logger.warn('[WeChat] Retrying getUpdates immediately with an empty sync cursor');
+                    continue;
+                }
                 consecutiveFailures++;
                 if (err instanceof WechatApiError) {
                     logger.error(`[WeChat] getUpdates API error (${consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES}): ${err.message}`);
@@ -470,6 +523,24 @@ export class WechatChannel {
             }
         }
     }
+    clearSyncCursor(reason, rejectedCursor) {
+        if (rejectedCursor)
+            this.lastRejectedSyncCursor = rejectedCursor;
+        this.getUpdatesBuf = '';
+        try {
+            let persistedAction = 'no persisted cursor';
+            if (fs.existsSync(this.syncBufPath)) {
+                const quarantinePath = `${this.syncBufPath}.corrupt-${Date.now()}`;
+                fs.renameSync(this.syncBufPath, quarantinePath);
+                persistedAction = `quarantined as ${path.basename(quarantinePath)}`;
+            }
+            logger.warn(`[WeChat] Cleared sync cursor: ${reason} (${persistedAction})`);
+        }
+        catch (err) {
+            logger.warn(`[WeChat] Cleared in-memory sync cursor but failed to quarantine persisted cursor: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // ── Inbound Message Handler ──────────────────────────────────────────
     async handleInboundMessage(msg) {
         if (msg.message_type !== MSG_TYPE_USER)