evolcore 0.0.1 → 0.0.3

package/dist/aun/msg/group.js

@@ -0,0 +1,1231 @@
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { TextDecoder } from 'util';
+import { createShortConnection } from '../rpc/index.js';
+import { getAidStore, loadClient, SLOT } from '../aid/store.js';
+import { uploadFileAndBuildPayload } from './upload.js';
+import { daemonTaskSendIpcTimeoutMs } from './p2p.js';
+import { checkGroupIndex, getGroupIndex } from './group-index.js';
+import { appendMessageLog, buildOutboundEntry, classifyAunPayloadForLog } from '../../core/message/message-log.js';
+import { chatDirPath } from '../../core/session/session-fs-store.js';
+import { readBestTaskRuntimeContext } from '../../cli/task-context.js';
+import { ipcQuery } from '../../ipc.js';
+import { resolvePaths } from '../../paths.js';
+import { AGENT_DELEGATION_TOKEN_ENV } from '../../core/auth/agent-delegation.js';
+function buildGroupPayload(body) {
+    return body.mode === 'text' ? { type: 'text', text: body.text } : { ...body.payload };
+}
+function groupMessageLogContent(body) {
+    return body.mode === 'text' ? body.text
+        : body.mode === 'file' ? `[file] ${body.filePath}`
+            : '[payload]';
+}
+function isCurrentGroupRuntime(args, runtimeContext) {
+    return runtimeContext?.channel === 'aun'
+        && runtimeContext.chatType === 'group'
+        && runtimeContext.selfAid === args.from
+        && runtimeContext.channelId === args.groupId;
+}
+function groupThreadId(args, payload, runtimeContext) {
+    const payloadThread = typeof payload?.thread_id === 'string' && payload.thread_id.trim()
+        ? payload.thread_id.trim()
+        : undefined;
+    return payloadThread || args.thread || (isCurrentGroupRuntime(args, runtimeContext) ? runtimeContext?.threadId : undefined);
+}
+function applyGroupRoutingPayloadFields(payload, args, runtimeContext) {
+    const threadId = groupThreadId(args, payload, runtimeContext);
+    if (threadId && typeof payload.thread_id !== 'string')
+        payload.thread_id = threadId;
+}
+function groupSendLogMetadata(args, payload, runtimeContext) {
+    const classified = payload ? classifyAunPayloadForLog(payload) : undefined;
+    return {
+        content: classified?.content ?? groupMessageLogContent(args.body),
+        sessionId: isCurrentGroupRuntime(args, runtimeContext) ? runtimeContext?.sessionId : undefined,
+        threadId: groupThreadId(args, payload, runtimeContext) ?? null,
+        msgType: classified?.msgType,
+        payloadType: classified?.payloadType,
+        payloadSummary: classified?.payloadSummary,
+        source: (runtimeContext ? 'msg' : 'cli'),
+    };
+}
+function appendGroupSendOutboundLog(args, messageId, payload, runtimeContext) {
+    const log = groupSendLogMetadata(args, payload, runtimeContext);
+    const chatDir = chatDirPath(resolvePaths().sessionsDir, 'aun', args.groupId, args.from);
+    fs.mkdirSync(chatDir, { recursive: true });
+    appendMessageLog(chatDir, buildOutboundEntry({
+        from: args.from,
+        to: args.groupId,
+        sessionId: log.sessionId,
+        threadId: log.threadId,
+        chatType: 'group',
+        groupId: args.groupId,
+        msgId: messageId,
+        content: log.content,
+        encrypt: args.encrypt === true,
+        msgType: log.msgType,
+        payloadType: log.payloadType,
+        payloadSummary: log.payloadSummary,
+        source: log.source,
+    }));
+}
+async function tryDaemonGroupSend(args, payload, runtimeContext, file) {
+    const delegatedTask = !!process.env.EVOLCORE_SESSION_ID
+        || !!process.env[AGENT_DELEGATION_TOKEN_ENV];
+    if (!runtimeContext) {
+        return delegatedTask
+            ? { ok: false, code: 'DELEGATION_REQUIRED', error: 'Task runtime context is unavailable' }
+            : null;
+    }
+    if (!runtimeContext.selfAid || runtimeContext.selfAid !== args.from) {
+        return { ok: false, code: 'INVALID_DELEGATION', error: 'Task sender does not match the delegated agent' };
+    }
+    if (!runtimeContext.sessionId || !runtimeContext.messageId) {
+        return { ok: false, code: 'INVALID_DELEGATION', error: 'Task runtime context is incomplete' };
+    }
+    if (args.slotId || args.aunPath) {
+        return { ok: false, code: 'INVALID_DELEGATION', error: 'Task sends cannot override the daemon AUN connection' };
+    }
+    const thread = groupThreadId(args, payload, runtimeContext);
+    const response = await ipcQuery(resolvePaths().socket, {
+        type: 'aun-msg-send',
+        aid: args.from,
+        to: args.groupId,
+        scope: 'group',
+        ...(payload ? { payload } : { file }),
+        mentions: args.mentions,
+        encrypt: args.encrypt === true,
+        thread,
+        returnPolicy: args.returnPolicy,
+        originSessionId: runtimeContext.sessionId,
+        originMessageId: runtimeContext.messageId,
+        delegationToken: process.env[AGENT_DELEGATION_TOKEN_ENV],
+        log: groupSendLogMetadata(args, payload, runtimeContext),
+    }, daemonTaskSendIpcTimeoutMs(!!file));
+    return response ?? {
+        ok: false,
+        code: 'AUN_DAEMON_UNAVAILABLE',
+        error: 'EvolCore daemon did not complete the delegated AUN group send',
+    };
+}
+async function daemonGroupSendResult(args, payload, runtimeContext, result) {
+    if (!result.ok) {
+        return {
+            ok: false,
+            error: result.error || 'daemon AUN group send failed',
+            code: result.code,
+            handoff_id: result.handoff_id,
+            target_session_id: result.target_session_id,
+        };
+    }
+    if (result.handoff_id) {
+        return {
+            ok: true,
+            group_id: result.group_id || args.groupId,
+            message_id: result.message_id,
+            handoff_id: result.handoff_id,
+            target_session_id: result.target_session_id,
+            status: result.status,
+        };
+    }
+    if (!result.group_id || !result.message) {
+        return { ok: false, error: 'daemon AUN group send returned no group message' };
+    }
+    const messageId = result.message_id
+        ?? (typeof result.message.message_id === 'string' ? result.message.message_id : undefined);
+    if (messageId && !result.log_written) {
+        appendGroupSendOutboundLog(args, messageId, payload, runtimeContext);
+    }
+    return {
+        ok: true,
+        group_id: result.group_id || args.groupId,
+        message: result.message,
+        event: result.event,
+    };
+}
+export async function groupSend(args) {
+    const runtimeContext = await readBestTaskRuntimeContext();
+    if (args.body.mode !== 'file') {
+        const payload = buildGroupPayload(args.body);
+        applyGroupRoutingPayloadFields(payload, args, runtimeContext);
+        const daemonResult = await tryDaemonGroupSend(args, payload, runtimeContext);
+        if (daemonResult)
+            return daemonGroupSendResult(args, payload, runtimeContext, daemonResult);
+    }
+    else {
+        const daemonResult = await tryDaemonGroupSend(args, undefined, runtimeContext, {
+            filePath: path.resolve(args.body.filePath),
+            as: args.body.as,
+            contentType: args.body.contentType,
+            text: args.body.text,
+            transcript: args.body.transcript,
+        });
+        if (daemonResult) {
+            const payload = { type: args.body.as || 'file' };
+            applyGroupRoutingPayloadFields(payload, args, runtimeContext);
+            return daemonGroupSendResult(args, payload, runtimeContext, daemonResult);
+        }
+    }
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        let payload;
+        switch (args.body.mode) {
+            case 'text':
+                payload = { type: 'text', text: args.body.text };
+                break;
+            case 'payload':
+                payload = args.body.payload;
+                break;
+            case 'file': {
+                const built = await uploadFileAndBuildPayload(conn, args.from, args.body.filePath, {
+                    as: args.body.as,
+                    contentType: args.body.contentType,
+                    text: args.body.text,
+                    transcript: args.body.transcript,
+                    onProgress: args.onUploadProgress,
+                });
+                payload = built.payload;
+                break;
+            }
+        }
+        if (args.mentions && args.mentions.length > 0) {
+            payload.mentions = args.mentions;
+        }
+        applyGroupRoutingPayloadFields(payload, args, runtimeContext);
+        const sendParams = { group_id: args.groupId, payload };
+        sendParams.encrypt = args.encrypt === true;
+        const result = await conn.call('group.send', sendParams);
+        const messageId = typeof result?.message?.message_id === 'string' ? result.message.message_id : undefined;
+        if (messageId)
+            appendGroupSendOutboundLog(args, messageId, payload, runtimeContext);
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            message: result?.message,
+            event: result?.event,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupPull(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = { group_id: args.groupId };
+        if (args.afterSeq !== undefined)
+            params.after_message_seq = args.afterSeq;
+        if (args.limit !== undefined)
+            params.limit = args.limit;
+        const result = await conn.call('group.pull', params);
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            messages: result?.messages ?? [],
+            latest_message_seq: result?.latest_message_seq ?? 0,
+            has_more: !!result?.has_more,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupAck(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.ack', { group_id: args.groupId, msg_seq: args.seq });
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            ack_seq: result?.cursor ?? result?.ack_seq ?? args.seq,
+            latest_message_seq: result?.latest_message_seq,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupCreate(args) {
+    const store = await getAidStore({ slotId: args.slotId ?? SLOT.cli, aunPath: args.aunPath });
+    const conn = await loadClient(store, args.from);
+    try {
+        await conn.connect({ connection_kind: 'short', short_ttl_ms: 30000, auto_reconnect: false });
+        const params = { name: args.name };
+        if (args.groupId)
+            params.group_id = args.groupId;
+        const groupName = groupNameFromGroupId(args.groupId);
+        if (groupName)
+            params.group_name = groupName;
+        if (args.visibility)
+            params.visibility = args.visibility;
+        if (args.description)
+            params.description = args.description;
+        if (args.joinMode)
+            params.join_mode = args.joinMode;
+        const result = await conn.createGroup(params);
+        return { ok: true, group: result?.group ?? result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+        try {
+            store.close();
+        }
+        catch { }
+    }
+}
+export async function groupInfo(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = { group_id: args.groupId };
+        if (args.required?.length)
+            params.required = args.required;
+        const result = await conn.call('group.get_info', params);
+        const raw = result?.group ?? result;
+        const found = result?.found !== false && !!raw && !!(raw.group_aid ?? raw.group_id);
+        return { ok: true, found, ...(found ? { group: normalizeGroupInfo(raw) } : {}) };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupList(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = {};
+        if (args.size !== undefined)
+            params.size = args.size;
+        if (args.page !== undefined)
+            params.page = args.page;
+        if (args.cursor !== undefined)
+            params.cursor = args.cursor;
+        const result = await conn.call('group.list_my', params);
+        const items = (result?.items ?? []).map(normalizeGroupInfo);
+        return {
+            ok: true,
+            items,
+            total: result?.total ?? 0,
+            page: result?.page ?? args.page ?? 1,
+            size: result?.size ?? args.size ?? items.length,
+            nextCursor: result?.next_cursor ?? result?.nextCursor ?? result?.cursor ?? null,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupUpdate(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = { group_id: args.groupId };
+        if (args.name !== undefined)
+            params.name = args.name;
+        if (args.description !== undefined)
+            params.description = args.description;
+        const result = await conn.call('group.update', params);
+        return { ok: true, group: result?.group };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupDissolve(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.dissolve', { group_id: args.groupId });
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            status: result?.status ?? 'dissolved',
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupSuspend(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.suspend', { group_id: args.groupId });
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupResume(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.resume', { group_id: args.groupId });
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupJoin(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = { group_id: args.groupId };
+        if (args.message)
+            params.message = args.message;
+        if (args.answer)
+            params.answer = args.answer;
+        const result = await conn.call('group.request_join', params);
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupLeave(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.leave', { group_id: args.groupId });
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupInvite(args) {
+    if (args.members.length === 0) {
+        return { ok: false, error: '至少需要一个成员 AID' };
+    }
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    const added = [];
+    const failed = [];
+    try {
+        for (const memberAid of args.members) {
+            try {
+                await conn.call('group.add_member', { group_id: args.groupId, aid: memberAid });
+                added.push(memberAid);
+            }
+            catch (e) {
+                failed.push({ aid: memberAid, error: String(e?.message ?? e) });
+            }
+        }
+        return { ok: true, group_id: args.groupId, added, failed };
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupKick(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.kick', { group_id: args.groupId, aid: args.memberAid });
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupMembers(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = { group_id: args.groupId };
+        if (args.page !== undefined)
+            params.page = args.page;
+        if (args.size !== undefined)
+            params.size = args.size;
+        const result = await conn.call('group.get_members', params);
+        return {
+            ok: true,
+            members: result?.members ?? [],
+            total: result?.total ?? 0,
+            page: result?.page ?? 1,
+            size: result?.size ?? 50,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupOnline(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.get_online_members', { group_id: args.groupId });
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            members: result?.members ?? [],
+            online_count: result?.online_count ?? 0,
+            total: result?.total ?? 0,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupSetRole(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.set_role', {
+            group_id: args.groupId,
+            aid: args.memberAid,
+            role: args.role,
+        });
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupTransferOwner(args) {
+    const store = await getAidStore({ slotId: args.slotId ?? SLOT.cli, aunPath: args.aunPath });
+    const conn = await loadClient(store, args.from);
+    try {
+        await conn.connect({ connection_kind: 'short', short_ttl_ms: 30000, auto_reconnect: false });
+        const start = await conn.startGroupTransfer({
+            group_id: args.groupId,
+            new_owner: args.newOwner,
+        }, { aidStore: store });
+        if (!ownerTransferNeedsCompletion(start)) {
+            return {
+                ok: true,
+                group_id: args.groupId,
+                data: { status: 'completed', auto_completed: false, start: normalizeRecord(start) },
+            };
+        }
+        try {
+            const newOwnerConn = await loadClient(store, args.newOwner);
+            try {
+                await newOwnerConn.connect({ connection_kind: 'short', short_ttl_ms: 30000, auto_reconnect: false });
+                const complete = await newOwnerConn.completeGroupTransfer({
+                    group_id: args.groupId,
+                }, { aidStore: store });
+                return {
+                    ok: true,
+                    group_id: args.groupId,
+                    data: {
+                        status: 'completed',
+                        auto_completed: true,
+                        start: normalizeRecord(start),
+                        complete: normalizeRecord(complete),
+                    },
+                };
+            }
+            finally {
+                await newOwnerConn.close();
+            }
+        }
+        catch (completeError) {
+            return {
+                ok: true,
+                group_id: args.groupId,
+                data: {
+                    status: 'pending_rekey',
+                    auto_completed: false,
+                    start: normalizeRecord(start),
+                    complete_error: errorMessage(completeError),
+                },
+            };
+        }
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+        try {
+            store.close();
+        }
+        catch { }
+    }
+}
+export async function groupBan(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = { group_id: args.groupId, aid: args.memberAid };
+        if (args.durationSeconds !== undefined)
+            params.duration_seconds = args.durationSeconds;
+        const result = await conn.call('group.ban', params);
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupUnban(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.unban', { group_id: args.groupId, aid: args.memberAid });
+        return { ok: true, group_id: args.groupId, data: result };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupBanlist(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.get_banlist', { group_id: args.groupId });
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            items: result?.items ?? [],
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupRules(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('group.get_rules', { group_id: args.groupId });
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            rules: result?.rules ?? result ?? {},
+        };
+    }
+    catch (e) {
+        if (e?.code === -32000 && String(e?.message ?? '').toLowerCase().includes('rules not found')) {
+            return { ok: true, group_id: args.groupId, rules: {} };
+        }
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function groupUpdateRules(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = { group_id: args.groupId };
+        if (args.mode !== undefined)
+            params.mode = args.mode;
+        if (args.question !== undefined)
+            params.question = args.question;
+        if (args.autoApprovePatterns !== undefined)
+            params.auto_approve_patterns = args.autoApprovePatterns;
+        if (args.maxPending !== undefined)
+            params.max_pending = args.maxPending;
+        const result = await conn.call('group.update_rules', params);
+        return {
+            ok: true,
+            group_id: result?.group_id ?? args.groupId,
+            rules: result?.rules ?? result ?? {},
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+const GROUP_RULES_FILE_PATH = '/rules.md';
+const MAX_GROUP_RULES_BYTES = 4 * 1024;
+const MTIME_TOLERANCE_MS = 1;
+export async function groupRulesFileGet(args) {
+    return withAunClient(args.from, args, async (client) => {
+        const resolved = await resolvePublishedRulesFile(client, args.groupId, true);
+        if (resolved.status !== 'ok') {
+            return {
+                ok: true,
+                group_id: args.groupId,
+                status: resolved.status,
+                path: GROUP_RULES_FILE_PATH,
+                metadata: resolved.metadata,
+                remote: resolved.remote,
+                error: resolved.error,
+            };
+        }
+        let bytes;
+        try {
+            bytes = await readGroupRulesBytes(client, args.groupId);
+        }
+        catch (e) {
+            return {
+                ok: true,
+                group_id: args.groupId,
+                status: rulesFileStatusFromError(e),
+                path: GROUP_RULES_FILE_PATH,
+                metadata: resolved.metadata,
+                remote: resolved.remote,
+                error: errorMessage(e),
+            };
+        }
+        if (bytes.byteLength > MAX_GROUP_RULES_BYTES) {
+            return {
+                ok: true,
+                group_id: args.groupId,
+                status: 'too_large',
+                path: GROUP_RULES_FILE_PATH,
+                metadata: resolved.metadata,
+            };
+        }
+        let content;
+        try {
+            content = decodeRulesText(bytes);
+        }
+        catch (e) {
+            return {
+                ok: true,
+                group_id: args.groupId,
+                status: 'unreadable',
+                path: GROUP_RULES_FILE_PATH,
+                metadata: resolved.metadata,
+                remote: resolved.remote,
+                error: `规则文件不是有效 UTF-8: ${errorMessage(e)}`,
+            };
+        }
+        return {
+            ok: true,
+            group_id: args.groupId,
+            status: 'ok',
+            path: GROUP_RULES_FILE_PATH,
+            metadata: resolved.metadata,
+            content,
+        };
+    });
+}
+export async function groupRulesFileSet(args) {
+    return withAunClient(args.from, args, async (client) => {
+        assertLocalRulesFile(args.filePath);
+        const upload = await client.group.fs.cp(args.filePath, `${args.groupId}:${GROUP_RULES_FILE_PATH}`, {
+            force: true,
+            overwrite: true,
+            parents: true,
+            contentType: 'text/markdown; charset=utf-8',
+        });
+        const published = await publishCurrentRulesFile(client, args.groupId, args.from);
+        return { ...published, upload };
+    });
+}
+export async function groupRulesFilePublish(args) {
+    return withAunClient(args.from, args, async (client) => {
+        return publishCurrentRulesFile(client, args.groupId, args.from);
+    });
+}
+// ==================== Internal ====================
+async function withAunClient(from, opts, fn) {
+    const store = await getAidStore({ slotId: opts.slotId ?? SLOT.cli, aunPath: opts.aunPath });
+    let client;
+    try {
+        client = await loadClient(store, from);
+        await client.connect({ connection_kind: 'short', short_ttl_ms: 30000, auto_reconnect: false });
+        return await fn(client);
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        if (client) {
+            try {
+                await client.close();
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            store.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+async function resolvePublishedRulesFile(client, groupId, forcePull) {
+    let content;
+    if (forcePull) {
+        try {
+            const index = await getGroupIndex(client, groupId);
+            const settings = isRecord(index.settings) ? index.settings : {};
+            content = settings['rules.content'];
+        }
+        catch (e) {
+            return {
+                status: rulesFileStatusFromError(e),
+                error: errorMessage(e),
+            };
+        }
+    }
+    else {
+        try {
+            const result = await client.group.getRules({ group_id: groupId });
+            const rules = isRecord(result.rules) ? result.rules : {};
+            content = rules.content;
+        }
+        catch (e) {
+            return {
+                status: rulesFileStatusFromError(e),
+                error: errorMessage(e),
+            };
+        }
+    }
+    if (content === undefined || content === null || content === '') {
+        return { status: 'missing' };
+    }
+    let metadata;
+    try {
+        metadata = parseRulesFileMetadata(content);
+    }
+    catch (e) {
+        return {
+            status: statusFromTaggedError(e) ?? 'invalid_metadata',
+            error: errorMessage(e),
+        };
+    }
+    if (metadata.size > MAX_GROUP_RULES_BYTES) {
+        return { status: 'too_large', metadata };
+    }
+    let remote;
+    try {
+        remote = metadataFromRulesStat(await client.group.fs.stat(`${groupId}:${GROUP_RULES_FILE_PATH}`));
+    }
+    catch (e) {
+        return {
+            status: rulesFileStatusFromError(e),
+            metadata,
+            error: errorMessage(e),
+        };
+    }
+    if (!remote.size || remote.mtimeMs === undefined) {
+        return {
+            status: 'unreadable',
+            metadata,
+            remote,
+            error: `远端 ${GROUP_RULES_FILE_PATH} 缺少 size 或 mtimeMs`,
+        };
+    }
+    if (!metadataMatches(metadata, remote)) {
+        return { status: 'file_mismatch', metadata, remote };
+    }
+    return { status: 'ok', metadata, remote };
+}
+async function publishCurrentRulesFile(client, groupId, actorAid) {
+    let metadata;
+    try {
+        metadata = metadataFromRulesStat(await client.group.fs.stat(`${groupId}:${GROUP_RULES_FILE_PATH}`));
+    }
+    catch (e) {
+        return {
+            ok: true,
+            group_id: groupId,
+            status: rulesFileStatusFromError(e),
+            path: GROUP_RULES_FILE_PATH,
+            error: errorMessage(e),
+        };
+    }
+    if (!metadata.size || metadata.mtimeMs === undefined) {
+        return {
+            ok: true,
+            group_id: groupId,
+            status: 'unreadable',
+            path: GROUP_RULES_FILE_PATH,
+            remote: metadata,
+            error: `远端 ${GROUP_RULES_FILE_PATH} 缺少 size 或 mtimeMs`,
+        };
+    }
+    const rulesMetadata = {
+        path: GROUP_RULES_FILE_PATH,
+        size: metadata.size,
+        mtimeMs: metadata.mtimeMs,
+    };
+    if (rulesMetadata.size > MAX_GROUP_RULES_BYTES) {
+        return {
+            ok: true,
+            group_id: groupId,
+            status: 'too_large',
+            path: GROUP_RULES_FILE_PATH,
+            metadata: rulesMetadata,
+        };
+    }
+    const publish = await client.group.updateRules({
+        group_id: groupId,
+        content: JSON.stringify(rulesMetadata),
+        attachments: [],
+    });
+    let after;
+    try {
+        after = metadataFromRulesStat(await client.group.fs.stat(`${groupId}:${GROUP_RULES_FILE_PATH}`));
+    }
+    catch (e) {
+        return {
+            ok: true,
+            group_id: groupId,
+            status: rulesFileStatusFromError(e),
+            path: GROUP_RULES_FILE_PATH,
+            metadata: rulesMetadata,
+            publish,
+            error: errorMessage(e),
+        };
+    }
+    if (!metadataMatches(rulesMetadata, after)) {
+        return {
+            ok: true,
+            group_id: groupId,
+            status: 'file_mismatch',
+            path: GROUP_RULES_FILE_PATH,
+            metadata: rulesMetadata,
+            remote: after,
+            publish,
+        };
+    }
+    const groupIndexEtag = groupIndexEtagFromUpdate(publish, groupId) ?? await currentGroupIndexEtag(client, groupId);
+    const notice = await sendGroupRulesUpdatedNotice(client, {
+        groupId,
+        actorAid,
+        metadata: rulesMetadata,
+        groupIndexEtag,
+    });
+    return {
+        ok: true,
+        group_id: groupId,
+        status: 'ok',
+        path: GROUP_RULES_FILE_PATH,
+        metadata: rulesMetadata,
+        publish,
+        group_index_etag: groupIndexEtag,
+        notice,
+    };
+}
+async function sendGroupRulesUpdatedNotice(client, args) {
+    const payload = {
+        type: 'notice',
+        subtype: 'group.rules.updated',
+        text: `群规则已发布：${args.groupId}:${GROUP_RULES_FILE_PATH}\n操作者：${args.actorAid}`,
+        actor_aid: args.actorAid,
+        group_id: args.groupId,
+        path: GROUP_RULES_FILE_PATH,
+        group_index_etag: args.groupIndexEtag,
+        size: args.metadata.size,
+        mtimeMs: args.metadata.mtimeMs,
+    };
+    try {
+        const result = await client.group.send({
+            group_id: args.groupId,
+            payload,
+            encrypt: false,
+        });
+        const message = isRecord(result.message) ? result.message : {};
+        const messageId = typeof result.message_id === 'string'
+            ? result.message_id
+            : typeof message.message_id === 'string'
+                ? message.message_id
+                : undefined;
+        return { ok: true, message_id: messageId };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.message || e) };
+    }
+}
+function assertLocalRulesFile(filePath) {
+    const st = fs.statSync(filePath);
+    if (!st.isFile()) {
+        throw new Error(`规则文件不是普通文件: ${filePath}`);
+    }
+    if (st.size > MAX_GROUP_RULES_BYTES) {
+        throw new Error(`规则文件过大: ${st.size} bytes > ${MAX_GROUP_RULES_BYTES}`);
+    }
+    const bytes = fs.readFileSync(filePath);
+    try {
+        decodeRulesText(bytes);
+    }
+    catch (e) {
+        throw new Error(`规则文件不是有效 UTF-8: ${errorMessage(e)}`);
+    }
+}
+async function readGroupRulesBytes(client, groupId) {
+    const remoteRef = `${groupId}:${GROUP_RULES_FILE_PATH}`;
+    const ticket = await client.call('group.fs.create_download_ticket', { path: remoteRef });
+    if (!isRecord(ticket)) {
+        throw new Error('group.fs.create_download_ticket returned invalid response');
+    }
+    const downloadUrl = stringField(ticket, ['download_url', 'url']);
+    if (!downloadUrl) {
+        throw new Error('group.fs.create_download_ticket did not return download_url');
+    }
+    const bytes = await client.group.fs.lowlevel.httpGet(downloadUrl, bearerHeaders(client));
+    const expectedSha = stringField(ticket, ['sha256']);
+    if (expectedSha && sha256Hex(bytes).toLowerCase() !== expectedSha.toLowerCase()) {
+        throw new Error('download hash verification failed');
+    }
+    return bytes;
+}
+function decodeRulesText(bytes) {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+}
+function parseRulesFileMetadata(value) {
+    let parsed;
+    if (typeof value === 'string') {
+        parsed = JSON.parse(value);
+    }
+    else {
+        parsed = value;
+    }
+    if (!isRecord(parsed)) {
+        throw statusError('invalid_metadata', 'rules.content metadata must be an object');
+    }
+    if (parsed.path !== GROUP_RULES_FILE_PATH) {
+        throw statusError('invalid_metadata', `rules.content.path must be ${GROUP_RULES_FILE_PATH}`);
+    }
+    const size = numberField(parsed, ['size']);
+    const mtimeMs = mtimeMsField(parsed);
+    if (size === undefined || !Number.isInteger(size) || size <= 0) {
+        throw statusError('invalid_metadata', 'rules.content.size must be a positive integer');
+    }
+    if (mtimeMs === undefined || !Number.isFinite(mtimeMs) || mtimeMs <= 0) {
+        throw statusError('invalid_metadata', 'rules.content.mtimeMs must be a valid millisecond timestamp');
+    }
+    return { path: GROUP_RULES_FILE_PATH, size, mtimeMs };
+}
+function metadataFromRulesStat(value) {
+    if (!isRecord(value))
+        return { path: GROUP_RULES_FILE_PATH };
+    return {
+        path: GROUP_RULES_FILE_PATH,
+        size: numberField(value, ['size', 'sizeBytes', 'size_bytes', 'bytes']),
+        mtimeMs: mtimeMsField(value),
+    };
+}
+function metadataMatches(expected, actual) {
+    return actual.size === expected.size
+        && actual.mtimeMs !== undefined
+        && Math.abs(actual.mtimeMs - expected.mtimeMs) <= MTIME_TOLERANCE_MS;
+}
+function groupIndexEtagFromUpdate(result, groupId) {
+    const meta = isRecord(result._meta) ? result._meta : {};
+    const groupIndexes = isRecord(meta.group_indexes) ? meta.group_indexes : {};
+    const direct = isRecord(groupIndexes[groupId]) ? groupIndexes[groupId] : undefined;
+    if (typeof direct?.etag === 'string')
+        return direct.etag;
+    for (const value of Object.values(groupIndexes)) {
+        if (isRecord(value) && typeof value.etag === 'string')
+            return value.etag;
+    }
+    return undefined;
+}
+function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function bearerHeaders(client) {
+    const token = accessTokenFromClient(client);
+    return token ? { Authorization: `Bearer ${token}` } : undefined;
+}
+function accessTokenFromClient(client) {
+    const anyClient = client;
+    if (typeof anyClient.getAccessToken === 'function') {
+        const token = stringValue(anyClient.getAccessToken());
+        if (token)
+            return token;
+    }
+    return stringValue(anyClient.accessToken)
+        || stringValue(anyClient.access_token)
+        || stringValue(anyClient._identity?.access_token)
+        || stringValue(anyClient._sessionParams?.access_token);
+}
+function stringField(obj, keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}
+async function currentGroupIndexEtag(client, groupId) {
+    try {
+        const check = await checkGroupIndex(client, groupId);
+        for (const key of ['remote_etag', 'local_etag', 'etag']) {
+            const value = check[key];
+            if (typeof value === 'string' && value)
+                return value;
+        }
+    }
+    catch {
+        // Fall through to a pulled index below.
+    }
+    try {
+        const index = await getGroupIndex(client, groupId);
+        const meta = isRecord(index.meta) ? index.meta : {};
+        return typeof meta.etag === 'string' ? meta.etag : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function statusError(status, message) {
+    const error = new Error(message);
+    error.groupRulesFileStatus = status;
+    return error;
+}
+function statusFromTaggedError(error) {
+    if (isRecord(error) && typeof error.groupRulesFileStatus === 'string') {
+        const status = error.groupRulesFileStatus;
+        if (isGroupRulesFileStatus(status))
+            return status;
+    }
+    return undefined;
+}
+function rulesFileStatusFromError(error) {
+    const tagged = statusFromTaggedError(error);
+    if (tagged)
+        return tagged;
+    const haystack = errorHaystack(error);
+    if (/(forbidden|unauthorized|permission|denied|no_permission|permission_denied|无权限|权限|拒绝|\b401\b|\b403\b)/i.test(haystack)) {
+        return 'forbidden';
+    }
+    if (/(not[_ -]?found|notfound|no such|enoent|missing|不存在|\b404\b|rules not found)/i.test(haystack)) {
+        return 'missing';
+    }
+    if (/(signature|verify|verification|signed_by|body_hash|invalid signature|验签|签名|json|metadata)/i.test(haystack)) {
+        return 'invalid_metadata';
+    }
+    if (/(timeout|temporar|unavailable|econn|network|socket|reset|下载|读取)/i.test(haystack)) {
+        return 'unreadable';
+    }
+    return 'error';
+}
+function isGroupRulesFileStatus(value) {
+    return value === 'ok'
+        || value === 'missing'
+        || value === 'forbidden'
+        || value === 'invalid_metadata'
+        || value === 'file_mismatch'
+        || value === 'too_large'
+        || value === 'unreadable'
+        || value === 'error';
+}
+function errorHaystack(error) {
+    if (!isRecord(error))
+        return errorMessage(error);
+    return [
+        error.name,
+        error.message,
+        error.code,
+        error.status,
+        error.statusCode,
+        error.error,
+    ].map(value => value === undefined ? '' : String(value)).join(' ');
+}
+function numberField(obj, keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value === 'string' && value.trim() && Number.isFinite(Number(value)))
+            return Number(value);
+    }
+    return undefined;
+}
+function stringValue(value) {
+    return value === undefined || value === null ? '' : String(value).trim();
+}
+function mtimeMsField(obj) {
+    const direct = numberField(obj, ['mtimeMs', 'mtime_ms', 'updatedAtMs', 'updated_at_ms']);
+    if (direct !== undefined)
+        return direct;
+    const seconds = numberField(obj, ['mtime', 'updated_at', 'updatedAt', 'last_modified', 'modified_at']);
+    if (seconds !== undefined)
+        return seconds > 10_000_000_000 ? seconds : seconds * 1000;
+    for (const key of ['modifiedAt', 'modified_at', 'mtime_iso']) {
+        const value = obj[key];
+        if (typeof value === 'string') {
+            const parsed = Date.parse(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeGroupInfo(value) {
+    const groupId = String(value?.group_aid ?? value?.group_id ?? '');
+    return {
+        ...value,
+        group_id: groupId,
+        ...(value?.group_aid ? { group_aid: String(value.group_aid) } : {}),
+        name: String(value?.name ?? groupId),
+    };
+}
+function formatRpcError(e) {
+    if (e?.code !== undefined && e?.message !== undefined) {
+        return { ok: false, error: String(e.message), code: e.code };
+    }
+    return { ok: false, error: String(e?.message ?? e) };
+}
+function normalizeRecord(value) {
+    return value && typeof value === 'object' ? value : { value };
+}
+function ownerTransferNeedsCompletion(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const data = value;
+    const status = String(data.status ?? data.transfer_status ?? '').toLowerCase();
+    return status === 'pending_rekey' || status === 'requires_ca_rekey' || data.requires_ca_rekey === true;
+}
+function errorMessage(e) {
+    if (e && typeof e === 'object' && 'message' in e)
+        return String(e.message);
+    return String(e);
+}
+function groupNameFromGroupId(groupId) {
+    if (!groupId)
+        return undefined;
+    const raw = String(groupId).trim().toLowerCase();
+    const first = raw.split(/[.@/]/, 1)[0] ?? '';
+    const slug = first.startsWith('g-') ? first.slice(2) : first;
+    if (/^[a-z0-9][a-z0-9_-]{3,63}$/.test(slug))
+        return slug;
+    return undefined;
+}