evolcore 0.0.26 → 0.0.27

package/dist/core/group/invite-service.js

@@ -0,0 +1,924 @@
+import { randomUUID } from 'node:crypto';
+import { atomicReadJson, atomicWriteJson } from '../../utils/atomic-write.js';
+import { agentGroupInviteReviewsPath } from '../../paths.js';
+import { normalizeGroupAid } from '../../aun/group/identity.js';
+import { isValidAid } from '../../aun/aid/validation.js';
+import { listStaticAgentOwners } from '../../config/peer-role-resolver.js';
+import { read, ConfigTarget } from '../../config/config-manager.js';
+import { resolveAgentLifecycle } from '../../config/lifecycle.js';
+import { logger } from '../../utils/logger.js';
+import { buildEnvelope, sendInteractionPayload, withEnvelopeReplyContext } from '../message/message-utils.js';
+import { renderActionAsText } from '../interaction-router.js';
+export const OPEN_INVITE_STATES = ['pending', 'processing', 'reconciling'];
+export function recordValue(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function strings(value) {
+    const items = Array.isArray(value) ? value : value === undefined ? [] : [value];
+    if (items.some(item => typeof item !== 'string' || !item.trim() || item.length > 1024)) {
+        throw new Error('Invalid group invitation identifiers');
+    }
+    return [...new Set(items.map(item => item.trim()))].sort();
+}
+/** Pending list entries are facts. Malformed entries must abort the entire snapshot, never look like absence. */
+export function normalizeGroupInvite(value, selfAid) {
+    if (!recordValue(value))
+        throw new Error('Invalid group invitation');
+    const invitee = value.invitee_aid ?? value.inviteeAid ?? selfAid;
+    if (typeof invitee !== 'string' || invitee.toLowerCase() !== selfAid.toLowerCase()) {
+        throw new Error('Group invitation belongs to another AID');
+    }
+    if (value.status !== undefined && typeof value.status !== 'string')
+        throw new Error('Invalid invitation status');
+    if (typeof value.status === 'string' && value.status.toLowerCase() !== 'pending') {
+        if (['accepted', 'rejected', 'revoked', 'expired'].includes(value.status.toLowerCase()))
+            return null;
+        throw new Error('Unknown invitation status');
+    }
+    const rawGroup = value.group_id ?? value.group_aid ?? value.groupId ?? value.groupAid;
+    if (typeof rawGroup !== 'string')
+        throw new Error('Group invitation is missing group AID');
+    const groupId = normalizeGroupAid(rawGroup);
+    const inviteIds = strings(value.invite_ids ?? value.invite_id ?? value.inviteIds);
+    if (!inviteIds.length)
+        throw new Error('Group invitation is missing invite IDs');
+    const inviterAids = strings(value.inviter_aids ?? value.inviter_aid ?? value.inviterAids);
+    if (inviterAids.some(aid => !isValidAid(aid)))
+        throw new Error('Invalid inviter AID');
+    const expiry = value.expires_at ?? value.expiresAt;
+    const expiresAt = typeof expiry === 'number'
+        ? (expiry < 1e12 ? expiry * 1000 : expiry)
+        : typeof expiry === 'string' ? Date.parse(expiry) : undefined;
+    if (expiry !== undefined && expiry !== null
+        && (expiresAt === undefined || !Number.isFinite(expiresAt) || expiresAt < 0)) {
+        throw new Error('Invalid invitation expiry');
+    }
+    return { selfAid, groupId, inviteIds, inviterAids,
+        ...(expiresAt !== undefined && Number.isFinite(expiresAt) && expiresAt > 0 ? { expiresAt } : {}) };
+}
+/** One daemon owns writes; the review service serializes async work per Agent. */
+export class GroupInviteReviewStore {
+    filePath;
+    constructor(filePath = agentGroupInviteReviewsPath) {
+        this.filePath = filePath;
+    }
+    read(selfAid) {
+        if (!isValidAid(selfAid))
+            throw new Error('Invalid review owner AID');
+        const snapshot = atomicReadJson(this.filePath(selfAid));
+        if (snapshot === null)
+            return { schemaVersion: 1, records: [] };
+        if (!recordValue(snapshot) || snapshot.schemaVersion !== 1 || !Array.isArray(snapshot.records)) {
+            throw new Error('Unsupported or corrupt group invitation review store');
+        }
+        const ids = new Set();
+        for (const item of snapshot.records) {
+            if (!recordValue(item) || item.selfAid !== selfAid || typeof item.reviewId !== 'string'
+                || !/^gir-[a-f0-9-]+$/.test(item.reviewId) || ids.has(item.reviewId)
+                || typeof item.groupId !== 'string' || normalizeGroupAid(item.groupId) !== item.groupId
+                || !Array.isArray(item.inviteIds) || !item.inviteIds.length || !Array.isArray(item.inviterAids)
+                || !['pending', 'processing', 'reconciling', 'accepted', 'rejected', 'stale'].includes(String(item.status))
+                || !Array.isArray(item.ownerDeliveries) || !Number.isFinite(item.updatedAt)
+                || !Number.isFinite(item.createdAt) || !Number.isSafeInteger(item.attempts)) {
+                throw new Error('Corrupt group invitation review record');
+            }
+            strings(item.inviteIds);
+            strings(item.inviterAids);
+            if (item.status === 'processing' || item.status === 'reconciling') {
+                if (!['accept', 'reject'].includes(String(item.decision)) || typeof item.actorAid !== 'string'
+                    || !isValidAid(item.actorAid) || typeof item.selectedInviteId !== 'string'
+                    || !item.inviteIds.includes(item.selectedInviteId) || typeof item.attemptId !== 'string') {
+                    throw new Error('Corrupt group invitation decision');
+                }
+            }
+            for (const delivery of item.ownerDeliveries) {
+                if (!recordValue(delivery) || typeof delivery.ownerAid !== 'string' || !isValidAid(delivery.ownerAid)
+                    || typeof delivery.interactionId !== 'string' || !delivery.interactionId.startsWith(`${item.reviewId}:`)
+                    || typeof delivery.operationId !== 'string' || !Number.isSafeInteger(delivery.generation)
+                    || !Number.isFinite(delivery.expiresAt) || !Array.isArray(delivery.messageIds)
+                    || !['prepared', 'sent', 'queued', 'failed', 'expired', 'invalidated'].includes(String(delivery.status))) {
+                    throw new Error('Corrupt group invitation delivery');
+                }
+            }
+            ids.add(item.reviewId);
+        }
+        return snapshot;
+    }
+    list(selfAid, states) {
+        return this.read(selfAid).records.filter(item => !states || states.includes(item.status));
+    }
+    create(invite) {
+        const normalized = normalizeGroupInvite(invite, invite.selfAid);
+        if (!normalized)
+            throw new Error('Cannot create a non-pending invitation');
+        invite = normalized;
+        const snapshot = this.read(invite.selfAid);
+        const open = snapshot.records.find(item => item.groupId === invite.groupId && OPEN_INVITE_STATES.includes(item.status));
+        if (open) {
+            if (invite.inviteIds.some(id => open.inviteIds.includes(id)))
+                return open;
+            throw new Error('Previous invitation round must be reconciled before creating a new round');
+        }
+        const record = {
+            ...invite, reviewId: `gir-${randomUUID()}`, status: 'pending', attempts: 0,
+            createdAt: Date.now(), updatedAt: Date.now(), ownerDeliveries: [],
+        };
+        snapshot.records.push(record);
+        this.write(invite.selfAid, snapshot);
+        return record;
+    }
+    update(selfAid, reviewId, change) {
+        const snapshot = this.read(selfAid);
+        const record = snapshot.records.find(item => item.reviewId === reviewId);
+        if (!record)
+            throw new Error('Group invitation review not found');
+        change(record);
+        record.updatedAt = Date.now();
+        if (['accepted', 'rejected', 'stale'].includes(record.status))
+            record.resolvedAt ??= Date.now();
+        this.write(selfAid, snapshot);
+        return record;
+    }
+    write(selfAid, snapshot) {
+        snapshot.records = snapshot.records.filter(item => OPEN_INVITE_STATES.includes(item.status)
+            || (item.resolvedAt ?? item.updatedAt) > Date.now() - 30 * 86400_000
+            || item.outcomeOwners?.some(owner => !item.outcomeDelivered?.includes(owner)));
+        atomicWriteJson(this.filePath(selfAid), snapshot);
+    }
+}
+/** Read every page, rejecting ambiguous/truncated/error responses before callers can reconcile absence. */
+export async function readGroupPages(client, method, fields, base = {}) {
+    const result = [];
+    const seenPages = new Set();
+    const seenCursors = new Set();
+    let cursor;
+    for (let page = 1; page <= 100; page++) {
+        const raw = await client.call(method, { ...base, ...(cursor ? { cursor } : { page }), size: 100 });
+        if (recordValue(raw) && (raw.ok === false || raw.error))
+            throw new Error(`${method} returned an error`);
+        const data = recordValue(raw) && recordValue(raw.data) ? raw.data : raw;
+        if (recordValue(data) && (data.ok === false || data.error))
+            throw new Error(`${method} returned an error`);
+        const rows = Array.isArray(data) ? data
+            : recordValue(data) ? fields.map(field => data[field]).find(Array.isArray) : undefined;
+        if (!Array.isArray(rows))
+            throw new Error(`${method} returned an invalid list`);
+        const signature = JSON.stringify(rows);
+        if (rows.length && seenPages.has(signature))
+            throw new Error(`${method} repeated a page`);
+        seenPages.add(signature);
+        result.push(...rows);
+        const meta = recordValue(data) ? { ...(recordValue(raw) ? raw : {}), ...data } : {};
+        if (meta.total !== undefined && (!Number.isSafeInteger(meta.total) || Number(meta.total) < 0)) {
+            throw new Error(`${method} returned an invalid total`);
+        }
+        const hasMore = meta.has_more ?? meta.hasMore;
+        if (hasMore !== undefined && typeof hasMore !== 'boolean')
+            throw new Error('Invalid has_more flag');
+        if (meta.size !== undefined && (!Number.isSafeInteger(meta.size) || Number(meta.size) <= 0)) {
+            throw new Error('Invalid page size');
+        }
+        const size = typeof meta.size === 'number' ? meta.size : 100;
+        const next = meta.next_cursor ?? meta.nextCursor ?? meta.cursor;
+        if (next !== undefined && next !== null && typeof next !== 'string')
+            throw new Error('Invalid next cursor');
+        if (typeof next === 'string' && next) {
+            if (seenCursors.has(next))
+                throw new Error(`${method} repeated a cursor`);
+            seenCursors.add(next);
+            cursor = next;
+            continue;
+        }
+        const more = hasMore === true || (typeof meta.total === 'number' && result.length < meta.total)
+            || (hasMore === undefined && meta.total === undefined && next === undefined && rows.length >= size);
+        if (!more)
+            return result;
+        if (!rows.length || cursor)
+            throw new Error(`${method} returned incomplete pagination`);
+    }
+    throw new Error(`${method} exceeded the page limit`);
+}
+export async function listPendingGroupInvites(client, selfAid) {
+    const raw = await readGroupPages(client, 'group.list_my_invites', ['items', 'invites']);
+    const groups = new Map();
+    for (const value of raw) {
+        const invite = normalizeGroupInvite(value, selfAid);
+        if (!invite)
+            continue;
+        const existing = groups.get(invite.groupId);
+        if (existing) {
+            existing.inviteIds = [...new Set([...existing.inviteIds, ...invite.inviteIds])].sort();
+            existing.inviterAids = [...new Set([...existing.inviterAids, ...invite.inviterAids])].sort();
+            if (invite.expiresAt !== undefined)
+                existing.expiresAt = Math.min(existing.expiresAt ?? Infinity, invite.expiresAt);
+        }
+        else
+            groups.set(invite.groupId, invite);
+    }
+    return [...groups.values()];
+}
+export async function isInvitedGroupMember(client, selfAid, groupId) {
+    if (client.aid !== selfAid)
+        throw new Error('Membership query identity mismatch');
+    const raw = await client.call('group.list_my', { size: 200 });
+    if (recordValue(raw) && (raw.ok === false || raw.error))
+        throw new Error('group.list_my returned an error');
+    const data = recordValue(raw) && recordValue(raw.data) ? raw.data : raw;
+    const groups = Array.isArray(data) ? data
+        : recordValue(data) ? ['items', 'groups'].map(key => data[key]).find(Array.isArray) : undefined;
+    if (!Array.isArray(groups))
+        throw new Error('group.list_my returned an invalid list');
+    const ids = groups.map(item => {
+        const id = recordValue(item) ? item.group_id ?? item.group_aid : undefined;
+        if (typeof id !== 'string')
+            throw new Error('Invalid group membership snapshot');
+        return normalizeGroupAid(id);
+    });
+    if (ids.includes(groupId))
+        return true;
+    const meta = recordValue(data) ? { ...(recordValue(raw) ? raw : {}), ...data } : {};
+    const total = meta.total;
+    const hasMore = meta.has_more ?? meta.hasMore;
+    const next = meta.next_cursor ?? meta.nextCursor ?? meta.cursor;
+    if (total !== undefined && (!Number.isSafeInteger(total) || Number(total) < groups.length)) {
+        throw new Error('group.list_my returned an invalid total');
+    }
+    if (hasMore !== undefined && typeof hasMore !== 'boolean')
+        throw new Error('Invalid membership pagination');
+    if (hasMore === true || next || (typeof total === 'number' && total > groups.length)
+        || (total === undefined && hasMore !== false && groups.length >= (Number(meta.size) || 200))) {
+        throw new Error('group.list_my membership snapshot is incomplete');
+    }
+    return false;
+}
+export async function decideGroupInvite(client, action, inviteId) {
+    const result = action === 'accept'
+        ? await client.group.acceptInvite({ invite_id: inviteId })
+        : await client.group.rejectInvite({ invite_id: inviteId });
+    if (recordValue(result) && (result.error || result.ok === false)) {
+        const message = recordValue(result.error) ? result.error.message : result.message;
+        throw new Error(typeof message === 'string' ? message : 'Gateway rejected the invitation decision');
+    }
+}
+const CARD_TTL_MS = 86400_000;
+const RECONCILE_TICK_MS = 30_000;
+const PAGE_SIZE = 10;
+const CARD_BATCH = 20;
+function cleanText(value, limit) {
+    return (value ?? '').replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, limit);
+}
+function latestDelivery(record, owner) {
+    return record.ownerDeliveries.filter(item => item.ownerAid === owner).sort((a, b) => b.generation - a.generation)[0];
+}
+function errorText(error) {
+    return (error instanceof Error ? error.message : String(error)).slice(0, 512);
+}
+/** The daemon is the sole writer. Snapshot reconciliation and decisions share one serial lane per Agent. */
+export class GroupInviteReviewService {
+    router;
+    store;
+    bindings = new Map();
+    lanes = new Map();
+    syncs = new Map();
+    timer;
+    constructor(router, store = new GroupInviteReviewStore()) {
+        this.router = router;
+        this.store = store;
+        this.timer = setInterval(() => {
+            for (const runtime of this.bindings.values())
+                if (runtime.nextSync <= Date.now())
+                    this.wake(runtime);
+        }, RECONCILE_TICK_MS);
+        this.timer.unref?.();
+    }
+    attach(binding) {
+        this.detach(binding.channelKey);
+        this.detach(binding.channelName);
+        const previous = this.bindings.get(binding.selfAid);
+        if (previous)
+            this.detach(previous.channelKey);
+        const runtime = { ...binding, ready: false, restored: false, nextSync: 0, failures: 0, registered: new Set() };
+        this.bindings.set(binding.selfAid, runtime);
+        binding.channel.setGroupInviteReviewHandlers({
+            onInvite: () => this.wake(runtime),
+            onConnected: () => { runtime.ready = false; this.wake(runtime); },
+            canDeliver: (id, owner) => this.canDeliver(runtime, id, owner),
+            onDelivered: (id, mid) => this.recordDelivery(runtime, id, mid),
+        });
+        if (binding.channel.isConnected())
+            this.wake(runtime);
+    }
+    detach(channelKey) {
+        for (const runtime of this.bindings.values()) {
+            if (runtime.channelKey !== channelKey && runtime.channelName !== channelKey)
+                continue;
+            this.bindings.delete(runtime.selfAid);
+            runtime.channel.setGroupInviteReviewHandlers(undefined);
+            for (const id of runtime.registered) {
+                void this.router.cancel(id, 'channel_stopped').catch(error => this.log(runtime.selfAid, error));
+            }
+            runtime.registered.clear();
+        }
+    }
+    async dispose() {
+        clearInterval(this.timer);
+        for (const runtime of [...this.bindings.values()])
+            this.detach(runtime.channelKey);
+        await Promise.allSettled(this.lanes.values());
+    }
+    configurationChanged(selfAid) {
+        const runtime = this.bindings.get(selfAid);
+        if (runtime)
+            this.wake(runtime);
+    }
+    owners(selfAid) {
+        return [...new Set(listStaticAgentOwners(selfAid, { fresh: true }).filter(isValidAid))];
+    }
+    active(runtime) {
+        const config = read(ConfigTarget.Agent, { self: runtime.selfAid }, { cache: false });
+        return this.bindings.get(runtime.selfAid) === runtime && !!config && config.enabled !== false
+            && resolveAgentLifecycle(config) === 'active';
+    }
+    client(runtime) {
+        if (!this.active(runtime) || !runtime.channel.isConnected())
+            throw new Error('Agent AUN 渠道尚未就绪');
+        const client = runtime.channel.getClient();
+        if (!client || client.aid !== runtime.selfAid)
+            throw new Error('AUN 客户端身份不匹配');
+        return client;
+    }
+    assertCurrent(runtime, client) {
+        if (this.client(runtime) !== client)
+            throw new Error('AUN 连接已更换，请重试');
+    }
+    serial(selfAid, work) {
+        const previous = this.lanes.get(selfAid) ?? Promise.resolve();
+        const task = previous.catch(() => undefined).then(work);
+        this.lanes.set(selfAid, task);
+        void task.finally(() => { if (this.lanes.get(selfAid) === task)
+            this.lanes.delete(selfAid); }).catch(() => undefined);
+        return task;
+    }
+    wake(runtime) {
+        if (this.bindings.get(runtime.selfAid) !== runtime)
+            return;
+        void this.reconcile(runtime.selfAid).catch(error => this.log(runtime.selfAid, error));
+    }
+    reconcile(selfAid) {
+        const existing = this.syncs.get(selfAid);
+        if (existing)
+            return existing;
+        const runtime = this.bindings.get(selfAid);
+        if (!runtime)
+            return Promise.reject(new Error('邀请审核服务未就绪'));
+        const task = this.serial(selfAid, async () => {
+            try {
+                await this.sync(runtime);
+                runtime.failures = 0;
+                const open = this.store.list(selfAid, OPEN_INVITE_STATES);
+                runtime.nextSync = Date.now() + (open.some(item => item.status !== 'pending') ? 30_000 : open.length ? 300_000 : 900_000);
+            }
+            catch (error) {
+                runtime.failures++;
+                runtime.nextSync = Date.now() + Math.min(900_000, 30_000 * 2 ** Math.min(runtime.failures, 5)) + Math.random() * 5000;
+                throw error;
+            }
+        });
+        this.syncs.set(selfAid, task);
+        void task.finally(() => { if (this.syncs.get(selfAid) === task)
+            this.syncs.delete(selfAid); }).catch(() => undefined);
+        return task;
+    }
+    async restore(runtime) {
+        if (runtime.restored)
+            return;
+        for (const record of this.store.list(runtime.selfAid)) {
+            for (const delivery of record.ownerDeliveries)
+                await this.invalidate(runtime, record.reviewId, delivery, 'daemon_restarted');
+            if (record.status === 'processing')
+                this.store.update(runtime.selfAid, record.reviewId, item => { item.status = 'reconciling'; });
+        }
+        runtime.restored = true;
+    }
+    async sync(runtime) {
+        const client = this.client(runtime);
+        await this.restore(runtime);
+        const pending = await listPendingGroupInvites(client, runtime.selfAid);
+        this.assertCurrent(runtime, client);
+        const byGroup = new Map(pending.map(invite => [invite.groupId, invite]));
+        for (const snapshot of this.store.list(runtime.selfAid, OPEN_INVITE_STATES)) {
+            const record = this.get(runtime.selfAid, snapshot.reviewId);
+            const fact = byGroup.get(record.groupId);
+            if (record.status !== 'pending') {
+                try {
+                    await this.recoverDecision(runtime, record, fact ?? null);
+                }
+                catch (error) {
+                    this.log(runtime.selfAid, error);
+                }
+                // An unresolved request may have committed. Keep the group locked until
+                // we can distinguish its outcome from a later invitation round.
+                const latest = this.get(runtime.selfAid, record.reviewId);
+                if (fact && (OPEN_INVITE_STATES.includes(latest.status)
+                    || fact.inviteIds.some(id => record.inviteIds.includes(id))))
+                    byGroup.delete(record.groupId);
+            }
+            else if (!fact || !fact.inviteIds.some(id => record.inviteIds.includes(id))) {
+                await this.finish(runtime, record, 'stale');
+            }
+            else {
+                const changed = JSON.stringify(record.inviteIds) !== JSON.stringify(fact.inviteIds)
+                    || JSON.stringify(record.inviterAids) !== JSON.stringify(fact.inviterAids)
+                    || record.expiresAt !== fact.expiresAt;
+                this.store.update(runtime.selfAid, record.reviewId, item => {
+                    item.inviteIds = fact.inviteIds;
+                    item.inviterAids = fact.inviterAids;
+                    item.expiresAt = fact.expiresAt;
+                });
+                byGroup.delete(record.groupId);
+                if (changed) {
+                    for (const delivery of record.ownerDeliveries) {
+                        if (['prepared', 'queued', 'sent'].includes(delivery.status)) {
+                            await this.invalidate(runtime, record.reviewId, delivery, 'invitation_updated');
+                        }
+                    }
+                }
+            }
+        }
+        this.assertCurrent(runtime, client);
+        for (const invite of byGroup.values()) {
+            const known = this.store.list(runtime.selfAid).some(record => record.groupId === invite.groupId
+                && record.inviteIds.some(id => invite.inviteIds.includes(id)));
+            if (!known)
+                this.store.create(invite);
+        }
+        runtime.ready = true;
+        let budget = CARD_BATCH;
+        for (const record of this.store.list(runtime.selfAid)) {
+            this.assertCurrent(runtime, client);
+            if (record.status === 'pending')
+                budget -= await this.ensureCards(runtime, record, budget);
+            else if (!OPEN_INVITE_STATES.includes(record.status))
+                await this.notifyOutcome(runtime, record);
+        }
+    }
+    get(selfAid, id) {
+        const record = this.store.list(selfAid).find(item => item.reviewId === id);
+        if (!record)
+            throw new Error('未找到邀请审核记录');
+        return record;
+    }
+    canDeliver(runtime, id, owner) {
+        if (this.bindings.get(runtime.selfAid) !== runtime || !this.active(runtime))
+            return 'stale';
+        if (!runtime.ready)
+            return 'defer';
+        try {
+            const record = this.store.list(runtime.selfAid).find(item => item.ownerDeliveries.some(d => d.interactionId === id));
+            const delivery = record?.ownerDeliveries.find(item => item.interactionId === id);
+            return record?.status === 'pending' && delivery?.ownerAid === owner && delivery.expiresAt > Date.now()
+                && ['prepared', 'queued', 'sent'].includes(delivery.status) && runtime.registered.has(id)
+                && this.owners(runtime.selfAid).includes(owner) ? 'allow' : 'stale';
+        }
+        catch {
+            return 'defer';
+        }
+    }
+    recordDelivery(runtime, id, mid) {
+        const record = this.store.list(runtime.selfAid).find(item => item.ownerDeliveries.some(d => d.interactionId === id));
+        if (!record)
+            return;
+        this.store.update(runtime.selfAid, record.reviewId, item => {
+            const delivery = item.ownerDeliveries.find(d => d.interactionId === id);
+            delivery.messageIds = [...new Set([...delivery.messageIds, mid])];
+            if (this.canDeliver(runtime, id, delivery.ownerAid) === 'allow')
+                delivery.status = 'sent';
+        });
+    }
+    async invalidate(runtime, id, delivery, reason) {
+        runtime.registered.delete(delivery.interactionId);
+        this.store.update(runtime.selfAid, id, record => {
+            const saved = record.ownerDeliveries.find(item => item.interactionId === delivery.interactionId);
+            if (saved.status !== 'expired')
+                saved.status = 'invalidated';
+        });
+        try {
+            await this.router.cancel(delivery.interactionId, reason);
+            if (runtime.channel.invalidateGroupInviteCard) {
+                await runtime.channel.invalidateGroupInviteCard(delivery.interactionId, delivery.ownerAid, delivery.messageIds);
+            }
+            else
+                await runtime.adapter.invalidateInteraction?.(delivery.interactionId, reason);
+        }
+        catch (error) {
+            this.log(runtime.selfAid, error);
+        }
+    }
+    async ensureCards(runtime, record, budget, reopenOwner) {
+        const owners = this.owners(runtime.selfAid);
+        for (const delivery of record.ownerDeliveries) {
+            if (!owners.includes(delivery.ownerAid) && !['invalidated', 'expired'].includes(delivery.status)) {
+                await this.invalidate(runtime, record.reviewId, delivery, 'owner_removed');
+            }
+        }
+        let sent = 0;
+        for (const owner of owners) {
+            if (sent >= budget || (reopenOwner && owner !== reopenOwner))
+                continue;
+            const current = this.get(runtime.selfAid, record.reviewId);
+            if (current.status !== 'pending')
+                break;
+            const latest = latestDelivery(current, owner);
+            if (latest) {
+                if (latest.expiresAt <= Date.now() && latest.status !== 'expired') {
+                    await this.invalidate(runtime, record.reviewId, latest, 'expired');
+                    this.store.update(runtime.selfAid, record.reviewId, item => {
+                        item.ownerDeliveries.find(d => d.interactionId === latest.interactionId).status = 'expired';
+                    });
+                }
+                if (!reopenOwner && (latest.status === 'expired' || latest.expiresAt <= Date.now()))
+                    continue;
+                if (!reopenOwner && latest.status === 'sent' && runtime.registered.has(latest.interactionId))
+                    continue;
+                if (!reopenOwner && latest.status === 'queued') {
+                    const state = latest.outboxId ? runtime.channel.getGroupInviteDeliveryState?.(latest.outboxId) : undefined;
+                    if (state?.status === 'sent' && state.messageId) {
+                        this.recordDelivery(runtime, latest.interactionId, state.messageId);
+                        continue;
+                    }
+                    if (state?.status === 'queued')
+                        continue;
+                    if (!state || state.status === 'missing') {
+                        await this.invalidate(runtime, record.reviewId, latest, 'outbox_missing');
+                        this.store.update(runtime.selfAid, record.reviewId, item => {
+                            item.ownerDeliveries.find(d => d.interactionId === latest.interactionId).status = 'failed';
+                        });
+                    }
+                }
+                if (!reopenOwner && latest.nextRetryAt && latest.nextRetryAt > Date.now())
+                    continue;
+                await this.invalidate(runtime, record.reviewId, latest, 'replaced');
+            }
+            const expiresAt = Math.min(Date.now() + CARD_TTL_MS, record.expiresAt ?? Infinity);
+            if (expiresAt <= Date.now())
+                continue;
+            const generation = (latest?.generation ?? 0) + 1;
+            const interactionId = `${record.reviewId}:${owner}:${generation}`;
+            const delivery = {
+                ownerAid: owner, generation, interactionId, operationId: `group-invite-review:${interactionId}`,
+                status: 'prepared', messageIds: [], expiresAt,
+            };
+            this.store.update(runtime.selfAid, record.reviewId, item => { item.ownerDeliveries.push(delivery); });
+            await this.deliverCard(runtime, record, delivery);
+            sent++;
+        }
+        return sent;
+    }
+    async deliverCard(runtime, record, delivery) {
+        const client = this.client(runtime);
+        const summary = await runtime.channel.getGroupInviteSummary(record.groupId);
+        this.assertCurrent(runtime, client);
+        const inviterText = record.inviterAids.slice(0, 5).join('、') || '未知';
+        const groupText = summary.name ? `${cleanText(summary.name, 120)}（${record.groupId}）` : record.groupId;
+        const body = [`受邀 Agent：${cleanText(runtime.agentName, 80)}（${record.selfAid}）`, `群聊：${groupText}`,
+            `邀请者：${inviterText}${record.inviterAids.length > 5 ? ` 等 ${record.inviterAids.length} 位` : ''}`,
+            `待处理邀请：${record.inviteIds.length} 条`,
+            ...(summary.description ? [`群简介：${cleanText(summary.description, 240)}`] : []),
+            '', '接受后，该 Agent 将作为成员加入此群。'].join('\n');
+        const interaction = {
+            type: 'interaction', id: delivery.interactionId, channelId: delivery.ownerAid,
+            sessionId: `group-invite:${record.reviewId}`, initiatorId: delivery.ownerAid,
+            blocking: false, expiresAt: delivery.expiresAt,
+            fallback: { command: 'invites', buttonArgMap: { accept: `${record.reviewId} accept`, reject: `${record.reviewId} reject` } },
+            kind: { kind: 'action', title: '群聊邀请待确认', bodyFormat: 'plain', body,
+                buttons: [{ key: 'accept', label: '接受入群', style: 'primary' }, { key: 'reject', label: '拒绝邀请', style: 'danger' }] },
+        };
+        runtime.registered.add(delivery.interactionId);
+        this.router.register(delivery.interactionId, interaction.sessionId, (action, values, operator, channelKey) => {
+            if (operator !== delivery.ownerAid || channelKey !== runtime.channelKey)
+                return false;
+            if (values?.behavior === 'dismiss') {
+                if (this.canDeliver(runtime, delivery.interactionId, operator) !== 'allow')
+                    return false;
+                runtime.registered.delete(delivery.interactionId);
+                void this.serial(runtime.selfAid, async () => {
+                    this.store.update(runtime.selfAid, record.reviewId, item => {
+                        item.ownerDeliveries.find(d => d.interactionId === delivery.interactionId).status = 'expired';
+                    });
+                    await this.invalidate(runtime, record.reviewId, delivery, 'dismissed');
+                }).catch(error => this.log(runtime.selfAid, error));
+                return true;
+            }
+            if (action !== 'accept' && action !== 'reject')
+                return false;
+            const claimed = this.claimDecision(runtime, record.reviewId, operator, action, delivery.interactionId);
+            if (!claimed.accepted) {
+                void this.notice(runtime, delivery.ownerAid, `retry:${delivery.interactionId}`, claimed.text);
+                runtime.registered.delete(delivery.interactionId);
+                return false;
+            }
+            void this.serial(runtime.selfAid, () => this.runClaimedDecision(runtime, claimed.record))
+                .catch(error => this.log(runtime.selfAid, error));
+            void this.notice(runtime, delivery.ownerAid, `claimed:${claimed.record.attemptId}`, '已记录你的决定，正在向群服务核实结果。');
+            return true;
+        }, {
+            blocking: false, initiatorId: delivery.ownerAid, initiatorChannelKey: runtime.channelKey,
+            timeoutMs: Math.max(1, delivery.expiresAt - Date.now()),
+            onTimeout: () => {
+                runtime.registered.delete(delivery.interactionId);
+                this.store.update(runtime.selfAid, record.reviewId, item => {
+                    item.ownerDeliveries.find(d => d.interactionId === delivery.interactionId).status = 'expired';
+                });
+                void Promise.resolve(runtime.adapter.invalidateInteraction?.(delivery.interactionId, 'expired'))
+                    .catch(error => this.log(runtime.selfAid, error));
+            },
+        });
+        try {
+            if (this.canDeliver(runtime, delivery.interactionId, delivery.ownerAid) !== 'allow') {
+                await this.invalidate(runtime, record.reviewId, delivery, 'owner_changed');
+                return;
+            }
+            const envelope = withEnvelopeReplyContext(this.envelope(runtime, delivery.ownerAid, delivery.operationId, interaction.sessionId), {
+                delivery: { chatType: 'private' }, attention: 'required',
+                metadata: { encrypted: true, source: 'daemon', chatmode: 'interactive', operationId: delivery.operationId },
+            });
+            const receipt = await sendInteractionPayload(runtime.adapter, envelope, interaction, renderActionAsText(interaction), envelope.replyContext);
+            if (!receipt || typeof receipt === 'string' || (receipt.status !== 'sent' && receipt.status !== 'queued')) {
+                throw new Error('群邀请卡片投递失败');
+            }
+            this.store.update(runtime.selfAid, record.reviewId, item => {
+                const saved = item.ownerDeliveries.find(d => d.interactionId === delivery.interactionId);
+                if (receipt.status === 'sent') {
+                    saved.messageIds = [...new Set([...saved.messageIds, ...receipt.messages.map(message => message.messageId)])];
+                    if (saved.status !== 'invalidated')
+                        saved.status = 'sent';
+                }
+                else if (saved.status !== 'sent' && saved.status !== 'invalidated') {
+                    saved.status = 'queued';
+                    saved.outboxId = receipt.outboxId;
+                }
+            });
+        }
+        catch (error) {
+            await this.invalidate(runtime, record.reviewId, delivery, 'delivery_failed');
+            this.store.update(runtime.selfAid, record.reviewId, item => {
+                const saved = item.ownerDeliveries.find(d => d.interactionId === delivery.interactionId);
+                saved.status = 'failed';
+                saved.nextRetryAt = Date.now() + 60_000;
+            });
+            this.log(runtime.selfAid, error);
+            await this.notice(runtime, delivery.ownerAid, `fallback:${delivery.interactionId}`, renderActionAsText(interaction));
+        }
+    }
+    envelope(runtime, owner, operationId, sessionId) {
+        return buildEnvelope({ operationId, taskId: operationId, sessionId, channel: runtime.channelName,
+            channelId: owner, agentName: runtime.agentName, chatmode: 'interactive', delivery: { chatType: 'private' },
+            replyContext: { delivery: { chatType: 'private' }, metadata: { operationId } } });
+    }
+    async notice(runtime, owner, operation, text) {
+        if (!this.active(runtime) || !this.owners(runtime.selfAid).includes(owner))
+            return false;
+        try {
+            const operationId = `group-invite-notice:${operation}:${owner}`;
+            const envelope = withEnvelopeReplyContext(this.envelope(runtime, owner, operationId), {
+                delivery: { chatType: 'private' }, attention: 'required',
+                metadata: { encrypted: true, source: 'daemon', chatmode: 'interactive', operationId },
+            });
+            const receipt = await runtime.adapter.send(envelope, { kind: 'command.result', text });
+            return !!receipt && (receipt.status === 'sent' || receipt.status === 'queued');
+        }
+        catch (error) {
+            this.log(runtime.selfAid, error);
+            return false;
+        }
+    }
+    async finish(runtime, record, status) {
+        const updated = this.store.update(runtime.selfAid, record.reviewId, item => {
+            item.status = status;
+            item.resolvedAt ??= Date.now();
+            item.outcomeOwners = [...new Set([...item.ownerDeliveries.map(d => d.ownerAid), ...(item.actorAid ? [item.actorAid] : [])])];
+            item.outcomeDelivered ??= [];
+        });
+        logger.info(`[GroupInviteReview] outcome self=${runtime.selfAid} review=${record.reviewId} status=${status}`);
+        for (const delivery of updated.ownerDeliveries)
+            await this.invalidate(runtime, record.reviewId, delivery, status);
+        if (status === 'accepted')
+            runtime.channel.refreshGroupInviteMembership?.(record.groupId);
+        await this.notifyOutcome(runtime, this.get(runtime.selfAid, record.reviewId));
+    }
+    async notifyOutcome(runtime, record) {
+        const text = record.status === 'accepted' ? `已确认加入群聊 ${record.groupId}。`
+            : record.status === 'rejected' ? `已拒绝群聊 ${record.groupId} 的邀请。`
+                : `群聊 ${record.groupId} 的这轮邀请已不再待处理，可能已撤回、过期或由其它客户端处理。`;
+        for (const owner of record.outcomeOwners ?? [...new Set([...record.ownerDeliveries.map(d => d.ownerAid), ...(record.actorAid ? [record.actorAid] : [])])]) {
+            if (record.outcomeDelivered?.includes(owner))
+                continue;
+            const revoked = !this.owners(runtime.selfAid).includes(owner);
+            if (revoked || await this.notice(runtime, owner, `outcome:${record.reviewId}`, text)) {
+                this.store.update(runtime.selfAid, record.reviewId, item => {
+                    item.outcomeDelivered = [...new Set([...(item.outcomeDelivered ?? []), owner])];
+                });
+            }
+        }
+    }
+    claimDecision(runtime, id, owner, action, interactionId) {
+        const record = this.get(runtime.selfAid, id);
+        if (!this.active(runtime) || !this.owners(runtime.selfAid).includes(owner))
+            return { accepted: false, text: '只有当前 Agent Owner 可以审核。' };
+        if (record.status !== 'pending')
+            return { accepted: false, text: OPEN_INVITE_STATES.includes(record.status)
+                    ? '该邀请正在核实处理结果，暂不接受其它决定。' : '这轮邀请已经处理或失效。' };
+        if (interactionId && this.canDeliver(runtime, interactionId, owner) !== 'allow')
+            return { accepted: false, text: '卡片已失效，请用 /invites 重新打开。' };
+        if (!runtime.ready)
+            return { accepted: false, text: '邀请状态尚未完成核实，请稍后重试。' };
+        const decision = this.store.update(runtime.selfAid, id, item => {
+            item.status = 'processing';
+            item.decision = action;
+            item.actorAid = owner;
+            item.selectedInviteId = item.inviteIds[0];
+            item.attemptId = randomUUID();
+            item.attempts++;
+            item.submittedAt = Date.now();
+            item.nextAttemptAt = Date.now() + 30_000;
+        });
+        runtime.nextSync = Math.min(runtime.nextSync, Date.now() + 30_000);
+        logger.info(`[GroupInviteReview] decision self=${runtime.selfAid} review=${id} actor=${owner} action=${action}`);
+        return { accepted: true, record: decision };
+    }
+    async runClaimedDecision(runtime, decision) {
+        try {
+            const client = this.client(runtime);
+            const current = this.get(runtime.selfAid, decision.reviewId);
+            if (current.status !== 'processing' || current.attemptId !== decision.attemptId)
+                return;
+            const pending = (await listPendingGroupInvites(client, runtime.selfAid)).find(item => item.groupId === decision.groupId);
+            this.assertCurrent(runtime, client);
+            const selected = pending?.inviteIds.find(invite => decision.inviteIds.includes(invite));
+            if (!selected) {
+                if (current.decision === 'accept') {
+                    const joined = await isInvitedGroupMember(client, runtime.selfAid, current.groupId);
+                    this.assertCurrent(runtime, client);
+                    if (joined) {
+                        await this.finish(runtime, current, 'accepted');
+                        return;
+                    }
+                }
+                this.store.update(runtime.selfAid, current.reviewId, item => {
+                    item.status = 'stale';
+                    item.resolvedAt = Date.now();
+                });
+                await this.finish(runtime, this.get(runtime.selfAid, current.reviewId), 'stale');
+                return;
+            }
+            if (selected !== current.selectedInviteId) {
+                this.store.update(runtime.selfAid, decision.reviewId, item => { item.selectedInviteId = selected; });
+            }
+            await this.executeDecision(runtime, this.get(runtime.selfAid, decision.reviewId), client);
+        }
+        catch (error) {
+            if (this.bindings.get(runtime.selfAid) !== runtime)
+                return;
+            const current = this.get(runtime.selfAid, decision.reviewId);
+            if (OPEN_INVITE_STATES.includes(current.status)) {
+                this.store.update(runtime.selfAid, decision.reviewId, item => {
+                    item.status = 'reconciling';
+                    item.error = errorText(error);
+                    item.nextAttemptAt = Date.now() + 30_000;
+                });
+                await this.notice(runtime, decision.actorAid, `uncertain:${decision.attemptId}`, '群邀请决定已记录，服务端结果暂未确认。系统会继续核实，此时不接受相反决定。');
+            }
+            this.log(runtime.selfAid, error);
+        }
+    }
+    async decide(runtime, id, owner, action, interactionId) {
+        const claimed = this.claimDecision(runtime, id, owner, action, interactionId);
+        if (!claimed.accepted)
+            return claimed;
+        await this.runClaimedDecision(runtime, claimed.record);
+        const result = this.get(runtime.selfAid, id);
+        return { accepted: true, groupId: result.groupId, status: result.status,
+            text: result.status === 'accepted' ? `已确认加入 ${result.groupId}。` : result.status === 'rejected'
+                ? `已拒绝 ${result.groupId} 的邀请。` : result.status === 'stale' ? '这轮邀请已不再待处理，未执行新的入群操作。' : '决定已记录，正在核实服务端结果；请稍后查看 /invites。' };
+    }
+    async executeDecision(runtime, record, client) {
+        try {
+            this.assertCurrent(runtime, client);
+            if (!this.owners(runtime.selfAid).includes(record.actorAid))
+                throw new Error('Owner 权限已变化，暂停重试');
+            await decideGroupInvite(client, record.decision, record.selectedInviteId);
+        }
+        catch (error) {
+            if (this.bindings.get(runtime.selfAid) !== runtime)
+                return;
+            const current = this.get(runtime.selfAid, record.reviewId);
+            if (!OPEN_INVITE_STATES.includes(current.status)) {
+                this.log(runtime.selfAid, error);
+                return;
+            }
+            this.store.update(runtime.selfAid, record.reviewId, item => {
+                item.status = 'reconciling';
+                item.error = errorText(error);
+                item.nextAttemptAt = Date.now() + Math.min(900_000, 30_000 * 2 ** Math.min(item.attempts - 1, 5));
+            });
+            this.log(runtime.selfAid, error);
+            await this.notice(runtime, record.actorAid, `uncertain:${record.attemptId}`, '群邀请决定已记录，服务端结果暂未确认。系统会继续核实，此时不接受相反决定。');
+            return;
+        }
+        // Persist the authoritative RPC outcome before best-effort invalidation and notifications.
+        const status = record.decision === 'accept' ? 'accepted' : 'rejected';
+        try {
+            await this.finish(runtime, record, status);
+        }
+        catch (error) {
+            this.log(runtime.selfAid, error);
+        }
+    }
+    async recoverDecision(runtime, record, pending) {
+        const client = this.client(runtime);
+        const selected = pending?.inviteIds.find(id => record.inviteIds.includes(id));
+        if (!selected) {
+            if (record.decision === 'accept') {
+                // Failure to read membership is unknown, not proof of non-membership.
+                const joined = await isInvitedGroupMember(client, runtime.selfAid, record.groupId);
+                this.assertCurrent(runtime, client);
+                if (joined) {
+                    await this.finish(runtime, record, 'accepted');
+                    return;
+                }
+            }
+            await this.finish(runtime, record, 'stale');
+            return;
+        }
+        if (selected !== record.selectedInviteId) {
+            this.store.update(runtime.selfAid, record.reviewId, item => { item.selectedInviteId = selected; });
+            record.selectedInviteId = selected;
+        }
+        if (record.nextAttemptAt && record.nextAttemptAt > Date.now())
+            return;
+        // Revocation stops future writes; never unlock the opposite action while an old request may have committed.
+        if (!this.owners(runtime.selfAid).includes(record.actorAid))
+            return;
+        const updated = this.store.update(runtime.selfAid, record.reviewId, item => {
+            item.status = 'reconciling';
+            item.attempts++;
+            item.submittedAt = Date.now();
+        });
+        await this.executeDecision(runtime, updated, client);
+    }
+    async decideManaged(selfAid, owner, inviteId, action) {
+        const runtime = this.bindings.get(selfAid);
+        if (!runtime || !this.owners(selfAid).includes(owner))
+            return { accepted: false, text: 'Agent Owner 审核通道不可用。' };
+        await this.reconcile(selfAid);
+        return this.serial(selfAid, async () => {
+            const record = this.store.list(selfAid, OPEN_INVITE_STATES).find(item => item.inviteIds.includes(inviteId));
+            return record ? this.decide(runtime, record.reviewId, owner, action) : { accepted: false, text: '邀请已失效或不存在。' };
+        });
+    }
+    async handleCommand(request) {
+        if (!/^\s*\/invites(?:\s|$)/i.test(request.content))
+            return { handled: false };
+        const runtime = this.bindings.get(request.selfAid);
+        const answer = (text) => ({ handled: true, text });
+        if (request.channelType !== 'aun' || request.chatType !== 'private' || !runtime
+            || request.channelKey !== runtime.channelKey || !this.owners(request.selfAid).includes(request.ownerAid)) {
+            return answer('请在当前 Agent Owner 的 AUN 私聊中查看或审核群邀请。');
+        }
+        const args = request.content.trim().split(/\s+/).slice(1);
+        try {
+            if (args.length === 2 && ['accept', 'reject'].includes(args[1])) {
+                const result = await this.serial(request.selfAid, () => this.decide(runtime, args[0], request.ownerAid, args[1]));
+                return answer(result.text);
+            }
+            if (args.length === 2 && args[1] === 'open') {
+                await this.reconcile(request.selfAid);
+                await this.serial(request.selfAid, async () => {
+                    const record = this.get(request.selfAid, args[0]);
+                    if (record.status !== 'pending')
+                        throw new Error('邀请已处理或正在核实');
+                    await this.ensureCards(runtime, record, 1, request.ownerAid);
+                });
+                return answer('已提交卡片投递；也可使用 /invites <审核编号> accept|reject。');
+            }
+            if (args.length > 1 || (args.length === 1 && !/^[1-9]\d{0,5}$/.test(args[0]))) {
+                return answer('用法：/invites [页码]；/invites <审核编号> open|accept|reject。');
+            }
+            await this.reconcile(request.selfAid);
+            const records = this.store.list(request.selfAid, OPEN_INVITE_STATES);
+            if (!records.length)
+                return answer('当前没有待处理的群邀请。');
+            const page = Math.min(Number(args[0] ?? 1), Math.ceil(records.length / PAGE_SIZE));
+            const rows = records.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);
+            const lines = rows.map(item => `${item.reviewId}\n群聊：${item.groupId}；${item.status === 'pending' ? '待审核' : '正在核实结果'}`);
+            return answer(`待处理邀请 ${records.length} 项，第 ${page}/${Math.ceil(records.length / PAGE_SIZE)} 页\n\n${lines.join('\n\n')}\n\n/invites <审核编号> open|accept|reject`);
+        }
+        catch (error) {
+            this.log(request.selfAid, error);
+            return answer(`暂时无法处理邀请：${errorText(error)}。待处理记录已保留。`);
+        }
+    }
+    log(selfAid, error) {
+        logger.warn(`[GroupInviteReview] self=${selfAid} ${errorText(error)}`);
+    }
+}