evolcore 0.0.11 → 0.0.12

package/dist/aun/msg/managed-operation.js

@@ -0,0 +1,804 @@
+import { TextDecoder } from 'util';
+import { getAidStore, loadClient, SLOT } from '../aid/index.js';
+import { msgHistory } from './history.js';
+import { msgOnline } from './p2p.js';
+import { resolveRoot } from '../../paths.js';
+import { isExplicitGroupId } from '../group-identity.js';
+import { isValidAid } from '../aid/validation.js';
+import { groupBan, groupBanlist, groupCreate, groupDissolve, groupInfo, groupInvite, groupJoin, groupKick, groupLeave, groupList, groupMembers, groupOnline, groupPull, groupAck, groupResume, groupRules, groupRulesFileGet, groupRulesFilePublish, groupRulesFileSet, groupSetRole, groupSuspend, groupTransferOwner, groupUnban, groupUpdate, groupUpdateRules, } from './group.js';
+/** Rules uploaded by a managed task are carried as bounded UTF-8 content. */
+export const MAX_MANAGED_GROUP_RULES_BYTES = 4 * 1024;
+const RELATION_GROUP_READ_KINDS = new Set([
+    'info',
+    'pull',
+    'members',
+    'online',
+    'rules.get',
+    'rules.get-legacy',
+]);
+/** Read operations that a user role may perform against its current group relation. */
+export function isManagedGroupRelationRead(command) {
+    return RELATION_GROUP_READ_KINDS.has(command.kind);
+}
+export class ManagedGroupOperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ManagedGroupOperationError';
+    }
+}
+const GROUP_VALUE_FLAGS = new Set([
+    '--format', '--after-seq', '--limit', '--visibility', '--description', '--join-mode', '--group-id',
+    '--name', '--page', '--size', '--mode', '--question', '--max-pending', '--message', '--answer', '--duration',
+]);
+function failGroup(code, reason) {
+    return { ok: false, code, reason };
+}
+function parseFlags(args) {
+    const positionals = [];
+    const values = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        if (token === '--aun-path' || token === '--app') {
+            return failGroup('NOT_ALLOWED', `${token} is not allowed for managed group operations`);
+        }
+        if (!GROUP_VALUE_FLAGS.has(token)) {
+            return failGroup('NOT_ALLOWED', `unsupported managed group option: ${token}`);
+        }
+        const value = args[++i];
+        if (value === undefined || value.startsWith('--')) {
+            return failGroup('INVALID_ARGUMENT', `${token} requires a value`);
+        }
+        if (values.has(token))
+            return failGroup('INVALID_ARGUMENT', `${token} may only be specified once`);
+        values.set(token, value);
+    }
+    const format = values.get('--format');
+    if (format !== undefined && format !== 'json')
+        return failGroup('INVALID_ARGUMENT', '--format only supports json');
+    return { positionals, values };
+}
+function requiredAid(value, label) {
+    const aid = String(value || '').trim().replace(/^@/, '');
+    if (!aid)
+        return failGroup('INVALID_ARGUMENT', `missing ${label}`);
+    if (!isValidAid(aid))
+        return failGroup('INVALID_AID', `invalid ${label}: ${aid}`);
+    return aid;
+}
+function requiredGroup(value) {
+    const groupId = String(value || '').trim();
+    if (!groupId)
+        return failGroup('INVALID_ARGUMENT', 'missing group AID');
+    if (!isExplicitGroupId(groupId))
+        return failGroup('INVALID_GROUP', `invalid group AID: ${groupId}`);
+    return groupId;
+}
+function numberFlag(flags, name) {
+    const raw = flags.get(name);
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        return failGroup('INVALID_ARGUMENT', `${name} must be a non-negative integer`);
+    }
+    return value;
+}
+function onlyFlags(flags, allowed) {
+    const accepted = new Set(['--format', ...allowed]);
+    for (const flag of flags.keys()) {
+        if (!accepted.has(flag))
+            return failGroup('NOT_ALLOWED', `${flag} is not allowed for this managed group command`);
+    }
+    return undefined;
+}
+function command(kind, operationId, canonicalArgv, from, extra = {}) {
+    return { ok: true, command: { kind, operationId, canonicalArgv, from, ...extra } };
+}
+function withFromAndGroup(sub, parsed, operationId, groupRequired = true) {
+    const from = requiredAid(parsed.positionals[0], 'from AID');
+    if (typeof from !== 'string')
+        return from;
+    let groupId;
+    if (groupRequired) {
+        const parsedGroup = requiredGroup(parsed.positionals[1]);
+        if (typeof parsedGroup !== 'string')
+            return parsedGroup;
+        groupId = parsedGroup;
+    }
+    return command(sub, operationId, ['group', sub, from, ...(groupId ? [groupId] : [])], from, groupId ? { groupId } : {});
+}
+/** Parse the restricted, self-scoped group command grammar used by the daemon. */
+export function resolveManagedGroupOperation(argv) {
+    const raw = argv[0] === 'group' ? argv.slice(1) : argv;
+    const sub = raw[0];
+    if (!sub || sub === 'send')
+        return failGroup('NOT_ALLOWED', 'managed group operations do not allow send; use the group send daemon route');
+    const parsed = parseFlags(raw.slice(1));
+    if (!('positionals' in parsed))
+        return parsed;
+    const { positionals, values } = parsed;
+    if (sub === 'list') {
+        const flagsError = onlyFlags(values, ['--size']);
+        if (flagsError)
+            return flagsError;
+        if (positionals.length !== 1)
+            return failGroup('INVALID_ARGUMENT', 'list accepts exactly <from>');
+        const base = withFromAndGroup(sub, parsed, 'ec.group.list', false);
+        if (!base.ok)
+            return base;
+        const size = numberFlag(values, '--size');
+        if (typeof size !== 'number' && size !== undefined)
+            return size;
+        return command(sub, 'ec.group.list', ['group', sub, base.command.from], base.command.from, { size });
+    }
+    if (sub === 'create') {
+        const flagsError = onlyFlags(values, ['--visibility', '--description', '--join-mode', '--group-id']);
+        if (flagsError)
+            return flagsError;
+        const from = requiredAid(positionals[0], 'from AID');
+        if (typeof from !== 'string')
+            return from;
+        const name = positionals[1];
+        if (!name || positionals.length !== 2)
+            return failGroup('INVALID_ARGUMENT', 'create accepts exactly <from> <name>');
+        const visibility = values.get('--visibility');
+        const joinMode = values.get('--join-mode');
+        if (visibility !== undefined && !['public', 'private'].includes(visibility))
+            return failGroup('INVALID_ARGUMENT', 'invalid --visibility');
+        if (joinMode !== undefined && !['open', 'approval', 'invite_only', 'closed'].includes(joinMode))
+            return failGroup('INVALID_ARGUMENT', 'invalid --join-mode');
+        const groupId = values.get('--group-id');
+        if (groupId !== undefined && !isExplicitGroupId(groupId))
+            return failGroup('INVALID_GROUP', `invalid --group-id: ${groupId}`);
+        return command(sub, 'ec.group.create', ['group', sub, from, name], from, { name, visibility, description: values.get('--description'), joinMode, groupId });
+    }
+    const simple = new Map([
+        ['pull', 'ec.group.pull'], ['ack', 'ec.group.ack'], ['info', 'ec.group.info'], ['update', 'ec.group.update'],
+        ['dissolve', 'ec.group.dissolve'], ['suspend', 'ec.group.suspend'], ['resume', 'ec.group.resume'],
+        ['join', 'ec.group.join'], ['leave', 'ec.group.leave'], ['invite', 'ec.group.invite'], ['kick', 'ec.group.kick'],
+        ['members', 'ec.group.members'], ['online', 'ec.group.online'], ['role', 'ec.group.role'], ['owner', 'ec.group.owner'],
+        ['ban', 'ec.group.ban'], ['unban', 'ec.group.unban'],
+    ]);
+    if (simple.has(sub)) {
+        const allowedFlags = {
+            pull: ['--after-seq', '--limit'], ack: [], info: [], update: ['--name', '--description'], dissolve: [],
+            suspend: [], resume: [], join: ['--message', '--answer'], leave: [], invite: [], kick: [],
+            members: ['--page', '--size'], online: [], role: [], owner: [], ban: ['--duration'], unban: [],
+        };
+        const flagsError = onlyFlags(values, allowedFlags[sub] ?? []);
+        if (flagsError)
+            return flagsError;
+        const base = withFromAndGroup(sub, parsed, simple.get(sub));
+        if (!base.ok)
+            return base;
+        const extra = {};
+        if (sub === 'pull') {
+            if (positionals.length !== 2)
+                return failGroup('INVALID_ARGUMENT', 'pull accepts exactly <from> <group-aid>');
+            const afterSeq = numberFlag(values, '--after-seq');
+            const limit = numberFlag(values, '--limit');
+            if (typeof afterSeq !== 'number' && afterSeq !== undefined)
+                return afterSeq;
+            if (typeof limit !== 'number' && limit !== undefined)
+                return limit;
+            Object.assign(extra, { afterSeq, limit });
+        }
+        else if (sub === 'ack') {
+            const seq = Number(positionals[2]);
+            if (positionals.length !== 3 || !Number.isInteger(seq) || seq < 0)
+                return failGroup('INVALID_ARGUMENT', 'ack requires a non-negative integer seq');
+            extra.seq = seq;
+        }
+        else if (sub === 'update') {
+            if (positionals.length !== 2 || (values.get('--name') === undefined && values.get('--description') === undefined))
+                return failGroup('INVALID_ARGUMENT', 'update requires --name or --description');
+            Object.assign(extra, { name: values.get('--name'), description: values.get('--description') });
+        }
+        else if (sub === 'join') {
+            if (positionals.length !== 2)
+                return failGroup('INVALID_ARGUMENT', 'join accepts exactly <from> <group-aid>');
+            Object.assign(extra, { message: values.get('--message'), answer: values.get('--answer') });
+        }
+        else if (sub === 'invite') {
+            if (positionals.length < 3)
+                return failGroup('INVALID_ARGUMENT', 'invite requires at least one member AID');
+            const members = positionals.slice(2);
+            for (const aid of members) {
+                const checked = requiredAid(aid, 'member AID');
+                if (typeof checked !== 'string')
+                    return checked;
+            }
+            extra.members = members;
+        }
+        else if (sub === 'kick' || sub === 'unban') {
+            if (positionals.length !== 3)
+                return failGroup('INVALID_ARGUMENT', `${sub} requires a member AID`);
+            const memberAid = requiredAid(positionals[2], 'member AID');
+            if (typeof memberAid !== 'string')
+                return memberAid;
+            extra.memberAid = memberAid;
+        }
+        else if (sub === 'members') {
+            if (positionals.length !== 2)
+                return failGroup('INVALID_ARGUMENT', 'members accepts exactly <from> <group-aid>');
+            const page = numberFlag(values, '--page');
+            const size = numberFlag(values, '--size');
+            if (typeof page !== 'number' && page !== undefined)
+                return page;
+            if (typeof size !== 'number' && size !== undefined)
+                return size;
+            Object.assign(extra, { page, size });
+        }
+        else if (sub === 'role') {
+            if (positionals.length !== 4)
+                return failGroup('INVALID_ARGUMENT', 'role requires member AID and admin|member');
+            const memberAid = requiredAid(positionals[2], 'member AID');
+            if (typeof memberAid !== 'string')
+                return memberAid;
+            if (!['admin', 'member'].includes(positionals[3]))
+                return failGroup('INVALID_ARGUMENT', 'role must be admin or member');
+            Object.assign(extra, { memberAid, role: positionals[3] });
+        }
+        else if (sub === 'owner') {
+            if (positionals.length !== 3)
+                return failGroup('INVALID_ARGUMENT', 'owner requires a new owner AID');
+            const newOwner = requiredAid(positionals[2], 'new owner AID');
+            if (typeof newOwner !== 'string')
+                return newOwner;
+            extra.newOwner = newOwner;
+        }
+        else if (sub === 'ban') {
+            if (positionals.length > 3)
+                return failGroup('INVALID_ARGUMENT', 'ban accepts at most one member AID');
+            if (positionals.length === 3) {
+                const memberAid = requiredAid(positionals[2], 'member AID');
+                if (typeof memberAid !== 'string')
+                    return memberAid;
+                extra.memberAid = memberAid;
+            }
+            const durationSeconds = numberFlag(values, '--duration');
+            if (typeof durationSeconds !== 'number' && durationSeconds !== undefined)
+                return durationSeconds;
+            extra.durationSeconds = durationSeconds;
+            extra.list = positionals.length === 2;
+        }
+        else if (sub === 'info' || sub === 'dissolve' || sub === 'suspend' || sub === 'resume' || sub === 'leave' || sub === 'online') {
+            if (positionals.length !== 2)
+                return failGroup('INVALID_ARGUMENT', `${sub} accepts exactly <from> <group-aid>`);
+        }
+        return command(sub, base.command.operationId, ['group', sub, base.command.from, ...(base.command.groupId ? [base.command.groupId] : [])], base.command.from, { groupId: base.command.groupId, ...extra });
+    }
+    if (sub === 'rules') {
+        const flagsError = onlyFlags(values, ['--mode', '--question', '--max-pending']);
+        if (flagsError)
+            return flagsError;
+        const from = requiredAid(positionals[0], 'from AID');
+        if (typeof from !== 'string')
+            return from;
+        const groupId = requiredGroup(positionals[1]);
+        if (typeof groupId !== 'string')
+            return groupId;
+        const rest = positionals.slice(2);
+        const action = rest[0];
+        if (action === 'get' || action === 'publish') {
+            const actionFlagsError = onlyFlags(values, []);
+            if (actionFlagsError)
+                return actionFlagsError;
+            if (rest.length !== 1)
+                return failGroup('INVALID_ARGUMENT', `rules ${action} accepts no positional arguments`);
+            return command(`rules.${action}`, `ec.group.rules.${action}`, ['group', 'rules', from, groupId, action], from, { groupId });
+        }
+        if (action === 'set') {
+            const actionFlagsError = onlyFlags(values, []);
+            if (actionFlagsError)
+                return actionFlagsError;
+            if (rest.length !== 2)
+                return failGroup('INVALID_ARGUMENT', 'rules set requires a file argument');
+            return command('rules.set', 'ec.group.rules.set', ['group', 'rules', from, groupId, 'set', '<rules-content>'], from, { groupId, filePath: rest[1] });
+        }
+        if (rest.length !== 0)
+            return failGroup('INVALID_ARGUMENT', 'unknown rules action');
+        const wantsUpdate = values.has('--mode') || values.has('--question') || values.has('--max-pending');
+        const operationId = wantsUpdate ? 'ec.group.rules.update' : 'ec.group.rules.read';
+        const mode = values.get('--mode');
+        if (mode !== undefined && !['open', 'approval', 'invite_only', 'closed'].includes(mode))
+            return failGroup('INVALID_ARGUMENT', 'invalid --mode');
+        const maxPending = numberFlag(values, '--max-pending');
+        if (typeof maxPending !== 'number' && maxPending !== undefined)
+            return maxPending;
+        return command(wantsUpdate ? 'rules.update' : 'rules.get-legacy', operationId, ['group', 'rules', from, groupId, ...(wantsUpdate ? ['update'] : ['read'])], from, { groupId, mode, question: values.get('--question'), maxPending });
+    }
+    return failGroup('NOT_ALLOWED', `unsupported managed group command: ${sub}`);
+}
+/** Execute a parsed command using daemon-owned AUN credentials and root. */
+export async function executeManagedGroupOperation(command, rulesContent) {
+    const opts = { aunPath: resolveRoot() };
+    let result;
+    switch (command.kind) {
+        case 'list':
+            result = await groupList({ from: command.from, size: command.size, ...opts });
+            break;
+        case 'create':
+            result = await groupCreate({ from: command.from, name: command.name, visibility: command.visibility, description: command.description, joinMode: command.joinMode, groupId: command.groupId, ...opts });
+            break;
+        case 'pull':
+            result = await groupPull({ from: command.from, groupId: command.groupId, afterSeq: command.afterSeq, limit: command.limit, ...opts });
+            break;
+        case 'ack':
+            result = await groupAck({ from: command.from, groupId: command.groupId, seq: command.seq, ...opts });
+            break;
+        case 'info':
+            result = await groupInfo({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'update':
+            result = await groupUpdate({ from: command.from, groupId: command.groupId, name: command.name, description: command.description, ...opts });
+            break;
+        case 'dissolve':
+            result = await groupDissolve({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'suspend':
+            result = await groupSuspend({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'resume':
+            result = await groupResume({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'join':
+            result = await groupJoin({ from: command.from, groupId: command.groupId, message: command.message, answer: command.answer, ...opts });
+            break;
+        case 'leave':
+            result = await groupLeave({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'invite':
+            result = await groupInvite({ from: command.from, groupId: command.groupId, members: command.members, ...opts });
+            break;
+        case 'kick':
+            result = await groupKick({ from: command.from, groupId: command.groupId, memberAid: command.memberAid, ...opts });
+            break;
+        case 'members':
+            result = await groupMembers({ from: command.from, groupId: command.groupId, page: command.page, size: command.size, ...opts });
+            break;
+        case 'online':
+            result = await groupOnline({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'role':
+            result = await groupSetRole({ from: command.from, groupId: command.groupId, memberAid: command.memberAid, role: command.role, ...opts });
+            break;
+        case 'owner':
+            result = await groupTransferOwner({ from: command.from, groupId: command.groupId, newOwner: command.newOwner, ...opts });
+            break;
+        case 'ban':
+            result = command.list ? await groupBanlist({ from: command.from, groupId: command.groupId, ...opts }) : await groupBan({ from: command.from, groupId: command.groupId, memberAid: command.memberAid, durationSeconds: command.durationSeconds, ...opts });
+            break;
+        case 'unban':
+            result = await groupUnban({ from: command.from, groupId: command.groupId, memberAid: command.memberAid, ...opts });
+            break;
+        case 'rules.get':
+            result = await groupRulesFileGet({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'rules.set':
+            if (typeof rulesContent !== 'string')
+                throw new ManagedGroupOperationError('RULES_CONTENT_REQUIRED', 'rules set requires validated rules content');
+            if (!rulesContent || Buffer.byteLength(rulesContent, 'utf8') > MAX_MANAGED_GROUP_RULES_BYTES || Buffer.from(rulesContent, 'utf8').toString('utf8') !== rulesContent) {
+                throw new ManagedGroupOperationError('INVALID_RULES_CONTENT', `rules content must be valid non-empty UTF-8 up to ${MAX_MANAGED_GROUP_RULES_BYTES} bytes`);
+            }
+            result = await groupRulesFileSet({ from: command.from, groupId: command.groupId, content: rulesContent, ...opts });
+            break;
+        case 'rules.publish':
+            result = await groupRulesFilePublish({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        case 'rules.update':
+            result = await groupUpdateRules({ from: command.from, groupId: command.groupId, mode: command.mode, question: command.question, maxPending: command.maxPending, ...opts });
+            break;
+        case 'rules.get-legacy':
+            result = await groupRules({ from: command.from, groupId: command.groupId, ...opts });
+            break;
+        default: throw new ManagedGroupOperationError('NOT_ALLOWED', `unsupported managed group operation: ${command.kind}`);
+    }
+    if (!result || result.ok !== true) {
+        throw new ManagedGroupOperationError('GROUP_OPERATION_FAILED', String(result?.error ?? 'group operation failed'));
+    }
+    return result;
+}
+export class ManagedMsgOperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ManagedMsgOperationError';
+    }
+}
+const HISTORY_VALUE_FLAGS = new Set([
+    '--session', '--limit', '--before', '--after', '--direction', '--format',
+]);
+function failMsg(code, reason) {
+    return { ok: false, code, reason };
+}
+function parseTime(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    if (/^-?\d+$/.test(trimmed)) {
+        const timestamp = Number(trimmed);
+        return Number.isSafeInteger(timestamp) ? timestamp : undefined;
+    }
+    const timestamp = Date.parse(trimmed);
+    return Number.isFinite(timestamp) ? timestamp : undefined;
+}
+/** Parse the daemon-owned, private-relation msg read grammar. */
+export function resolveManagedMsgOperation(argv) {
+    const raw = argv[0] === 'msg' ? argv.slice(1) : argv;
+    const kind = raw[0];
+    if (kind !== 'history' && kind !== 'online') {
+        return failMsg('NOT_ALLOWED', `unsupported managed msg command: ${kind || '<missing>'}`);
+    }
+    const from = String(raw[1] || '').replace(/^@/, '');
+    const target = String(raw[2] || '').replace(/^@/, '');
+    if (!isValidAid(from))
+        return failMsg('INVALID_AID', `invalid from AID: ${from || '<missing>'}`);
+    if (!isValidAid(target))
+        return failMsg('INVALID_AID', `invalid target AID: ${target || '<missing>'}`);
+    if (kind === 'online') {
+        const allowed = new Set(['--format']);
+        let format;
+        for (let index = 3; index < raw.length; index++) {
+            const flag = raw[index];
+            if (!allowed.has(flag))
+                return failMsg('NOT_ALLOWED', `unsupported managed online option: ${flag}`);
+            if (format !== undefined)
+                return failMsg('INVALID_ARGUMENT', '--format may only be specified once');
+            format = raw[++index];
+            if (!format || format.startsWith('--'))
+                return failMsg('INVALID_ARGUMENT', '--format requires a value');
+        }
+        if (format !== undefined && format !== 'json')
+            return failMsg('INVALID_ARGUMENT', '--format only supports json');
+        return {
+            ok: true,
+            command: {
+                kind,
+                operationId: 'ec.msg.online',
+                canonicalArgv: ['msg', kind, from, target],
+                from,
+                target,
+            },
+        };
+    }
+    const values = new Map();
+    for (let index = 3; index < raw.length; index++) {
+        const flag = raw[index];
+        if (flag === '--aun-path' || flag === '--app' || flag === '--channel' || flag === '--channel-name') {
+            return failMsg('NOT_ALLOWED', `${flag} is not allowed for managed msg history`);
+        }
+        if (!HISTORY_VALUE_FLAGS.has(flag))
+            return failMsg('NOT_ALLOWED', `unsupported managed history option: ${flag}`);
+        if (values.has(flag))
+            return failMsg('INVALID_ARGUMENT', `${flag} may only be specified once`);
+        const value = raw[++index];
+        if (!value || value.startsWith('--'))
+            return failMsg('INVALID_ARGUMENT', `${flag} requires a value`);
+        values.set(flag, value);
+    }
+    const format = values.get('--format');
+    if (format !== undefined && format !== 'text' && format !== 'json') {
+        return failMsg('INVALID_ARGUMENT', '--format only supports text|json');
+    }
+    const limitRaw = values.get('--limit');
+    const limit = limitRaw === undefined ? undefined : Number(limitRaw);
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 500)) {
+        return failMsg('INVALID_ARGUMENT', '--limit must be an integer from 1 to 500');
+    }
+    const direction = values.get('--direction');
+    if (direction !== undefined && !['in', 'out', 'all'].includes(direction)) {
+        return failMsg('INVALID_ARGUMENT', '--direction only supports in|out|all');
+    }
+    const beforeRaw = values.get('--before');
+    const afterRaw = values.get('--after');
+    const before = beforeRaw === undefined ? undefined : parseTime(beforeRaw);
+    const after = afterRaw === undefined ? undefined : parseTime(afterRaw);
+    if (beforeRaw !== undefined && before === undefined)
+        return failMsg('INVALID_ARGUMENT', 'invalid --before time');
+    if (afterRaw !== undefined && after === undefined)
+        return failMsg('INVALID_ARGUMENT', 'invalid --after time');
+    if (before !== undefined && after !== undefined && after >= before) {
+        return failMsg('INVALID_ARGUMENT', '--after must be earlier than --before');
+    }
+    return {
+        ok: true,
+        command: {
+            kind,
+            operationId: 'ec.msg.history',
+            canonicalArgv: ['msg', kind, from, target],
+            from,
+            target,
+            session: values.get('--session'),
+            limit,
+            before,
+            after,
+            direction,
+        },
+    };
+}
+/** Execute using daemon-owned AUN state and credentials. */
+export async function executeManagedMsgOperation(command) {
+    const result = command.kind === 'history'
+        ? msgHistory({
+            from: command.from,
+            target: command.target,
+            channel: 'aun',
+            session: command.session,
+            limit: command.limit,
+            before: command.before,
+            after: command.after,
+            direction: command.direction,
+        })
+        : await msgOnline({
+            from: command.from,
+            targets: [command.target],
+            aunPath: resolveRoot(),
+        });
+    if (!result || result.ok !== true) {
+        throw new ManagedMsgOperationError(typeof result?.code === 'string' ? result.code : 'MSG_OPERATION_FAILED', String(result?.error ?? 'msg operation failed'));
+    }
+    return result;
+}
+export const MAX_MANAGED_FS_CAT_BYTES = 256 * 1024;
+const MAX_MANAGED_FS_HEAD_BYTES = 4096;
+const MAX_REMOTE_PATH_LENGTH = 2048;
+export class ManagedFsOperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ManagedFsOperationError';
+    }
+}
+const FS_VALUE_FLAGS = new Set([
+    '--as', '--format', '--max-bytes', '--head-bytes', '--name', '--pattern', '--type', '--node-type',
+    '--size', '--mtime', '--page', '--page-size',
+]);
+function failFs(code, reason) {
+    return { ok: false, code, reason };
+}
+function positiveInteger(value, flag, max) {
+    if (value === undefined)
+        return undefined;
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < 1 || number > max) {
+        return failFs('INVALID_ARGUMENT', `${flag} must be an integer from 1 to ${max}`);
+    }
+    return number;
+}
+function parseRemote(value, allowEmpty) {
+    if (!value)
+        return failFs('INVALID_ARGUMENT', 'missing remote group path');
+    const separator = value.indexOf(':');
+    if (separator <= 0)
+        return failFs('INVALID_PATH', 'remote path must use <group-aid>:<absolute-path>');
+    const groupId = value.slice(0, separator).trim();
+    const remotePath = value.slice(separator + 1);
+    if (!isValidAid(groupId) || !isExplicitGroupId(groupId)) {
+        return failFs('INVALID_GROUP', `invalid group AID: ${groupId}`);
+    }
+    if (remotePath === '' && allowEmpty)
+        return { groupId, remotePath: '' };
+    if (!remotePath.startsWith('/') || remotePath.length > MAX_REMOTE_PATH_LENGTH || /[\u0000-\u001f\u007f]/.test(remotePath)) {
+        return failFs('INVALID_PATH', 'remote group path must be a bounded absolute path');
+    }
+    return { groupId, remotePath };
+}
+/** Parse the daemon-owned, current-group read-only filesystem grammar. */
+export function resolveManagedFsOperation(argv) {
+    const raw = argv[0] === 'fs' ? argv.slice(1) : argv;
+    const kind = raw[0];
+    if (!kind || !['ls', 'stat', 'lstat', 'cat', 'find', 'df'].includes(kind)) {
+        return failFs('NOT_ALLOWED', `unsupported managed fs command: ${kind || '<missing>'}`);
+    }
+    const values = new Map();
+    const positionals = [];
+    let follow = false;
+    for (let index = 1; index < raw.length; index++) {
+        const token = raw[index];
+        if (token === '-L' || token === '--follow') {
+            if (kind !== 'stat')
+                return failFs('NOT_ALLOWED', `${token} is only allowed for stat`);
+            follow = true;
+            continue;
+        }
+        if (!token.startsWith('-')) {
+            positionals.push(token);
+            continue;
+        }
+        if (token === '--aun-path' || token === '--app' || token === '--token') {
+            return failFs('NOT_ALLOWED', `${token} is not allowed for managed fs operations`);
+        }
+        if (!FS_VALUE_FLAGS.has(token))
+            return failFs('NOT_ALLOWED', `unsupported managed fs option: ${token}`);
+        if (values.has(token))
+            return failFs('INVALID_ARGUMENT', `${token} may only be specified once`);
+        const value = raw[++index];
+        if (!value || value.startsWith('--'))
+            return failFs('INVALID_ARGUMENT', `${token} requires a value`);
+        values.set(token, value);
+    }
+    if (positionals.length !== 1)
+        return failFs('INVALID_ARGUMENT', `${kind} accepts exactly one remote group path`);
+    const actorAidValue = values.get('--as');
+    const actorAid = actorAidValue === undefined ? undefined : actorAidValue.replace(/^@/, '');
+    if (actorAid !== undefined && !isValidAid(actorAid))
+        return failFs('INVALID_AID', `invalid --as AID: ${actorAid || '<missing>'}`);
+    const format = values.get('--format');
+    if (format !== undefined && format !== 'json')
+        return failFs('INVALID_ARGUMENT', '--format only supports json');
+    const allowedByKind = {
+        ls: new Set(['--as', '--format']),
+        stat: new Set(['--as', '--format']),
+        lstat: new Set(['--as', '--format']),
+        cat: new Set(['--as', '--format', '--max-bytes', '--head-bytes']),
+        find: new Set(['--as', '--format', '--name', '--pattern', '--type', '--node-type', '--size', '--mtime', '--page', '--page-size']),
+        df: new Set(['--as', '--format']),
+    };
+    for (const flag of values.keys()) {
+        if (!allowedByKind[kind].has(flag))
+            return failFs('NOT_ALLOWED', `${flag} is not allowed for managed fs ${kind}`);
+    }
+    const remote = parseRemote(positionals[0], kind === 'df');
+    if (!('groupId' in remote))
+        return remote;
+    const effectiveKind = kind === 'stat' && !follow ? 'lstat' : kind;
+    const maxBytes = positiveInteger(values.get('--max-bytes'), '--max-bytes', MAX_MANAGED_FS_CAT_BYTES);
+    if (typeof maxBytes !== 'number' && maxBytes !== undefined)
+        return maxBytes;
+    const headBytes = positiveInteger(values.get('--head-bytes'), '--head-bytes', MAX_MANAGED_FS_HEAD_BYTES);
+    if (typeof headBytes !== 'number' && headBytes !== undefined)
+        return headBytes;
+    const page = positiveInteger(values.get('--page'), '--page', 10_000);
+    if (typeof page !== 'number' && page !== undefined)
+        return page;
+    const pageSize = positiveInteger(values.get('--page-size'), '--page-size', 200);
+    if (typeof pageSize !== 'number' && pageSize !== undefined)
+        return pageSize;
+    const nodeType = values.get('--type') ?? values.get('--node-type');
+    if (nodeType !== undefined && !['f', 'd', 'l'].includes(nodeType)) {
+        return failFs('INVALID_ARGUMENT', '--type only supports f|d|l');
+    }
+    return {
+        ok: true,
+        command: {
+            kind: effectiveKind,
+            operationId: `ec.fs.${effectiveKind}`,
+            canonicalArgv: ['fs', effectiveKind, `${remote.groupId}:${remote.remotePath}`, ...(actorAid ? ['--as', actorAid] : [])],
+            actorAid,
+            groupId: remote.groupId,
+            remotePath: remote.remotePath,
+            maxBytes,
+            headBytes,
+            name: values.get('--name') ?? values.get('--pattern'),
+            nodeType,
+            size: values.get('--size'),
+            mtime: values.get('--mtime'),
+            page,
+            pageSize,
+        },
+    };
+}
+function numberFrom(value, keys) {
+    for (const key of keys) {
+        const number = Number(value?.[key]);
+        if (Number.isFinite(number))
+            return number;
+    }
+    return undefined;
+}
+function bytesFromDownload(value) {
+    const candidate = value?.bytes ?? value?.data ?? value?.content ?? value?.blob ?? value;
+    if (candidate instanceof Uint8Array)
+        return candidate;
+    if (Buffer.isBuffer(candidate))
+        return new Uint8Array(candidate);
+    if (typeof candidate === 'string')
+        return new Uint8Array(Buffer.from(candidate, 'base64'));
+    if (Array.isArray(candidate))
+        return new Uint8Array(candidate);
+    throw new ManagedFsOperationError('FS_DOWNLOAD_INVALID', 'group filesystem returned an unsupported blob');
+}
+async function withClient(actorAid, fn) {
+    const store = await getAidStore({ slotId: SLOT.cli, aunPath: resolveRoot() });
+    let client;
+    try {
+        client = await loadClient(store, actorAid);
+        await client.connect({ connection_kind: 'short', short_ttl_ms: 30000, auto_reconnect: false });
+        return await fn(client);
+    }
+    finally {
+        if (client) {
+            try {
+                await client.close();
+            }
+            catch { /* best effort */ }
+        }
+        try {
+            store.close();
+        }
+        catch { /* best effort */ }
+    }
+}
+/** Execute a parsed read against the current group using daemon-owned credentials. */
+export async function executeManagedFsOperation(command) {
+    if (!command.actorAid)
+        throw new ManagedFsOperationError('INVALID_ACTOR', 'managed fs actor is required');
+    const ref = `${command.groupId}:${command.remotePath}`;
+    try {
+        return await withClient(command.actorAid, async (client) => {
+            switch (command.kind) {
+                case 'ls': {
+                    const raw = await client.group.fs.ls(ref);
+                    const value = raw;
+                    const items = Array.isArray(value) ? value : value?.items ?? value?.nodes ?? value?.entries ?? [];
+                    return { ok: true, command: 'ls', path: ref, items };
+                }
+                case 'stat':
+                    return { ok: true, command: 'stat', path: ref, node: await client.group.fs.stat(ref) };
+                case 'lstat':
+                    return { ok: true, command: 'lstat', path: ref, node: await client.group.fs.lstat(ref) };
+                case 'find': {
+                    const raw = await client.group.fs.find(ref, {
+                        name: command.name,
+                        pattern: command.name,
+                        type: command.nodeType,
+                        size: command.size,
+                        mtime: command.mtime,
+                        page: command.page,
+                        page_size: command.pageSize,
+                    });
+                    const value = raw;
+                    const items = Array.isArray(value) ? value : value?.items ?? value?.nodes ?? value?.entries ?? [];
+                    return { ok: true, command: 'find', path: ref, items };
+                }
+                case 'df':
+                    return { ok: true, command: 'df', path: `${command.groupId}:`, usage: await client.group.fs.df(`${command.groupId}:`) };
+                case 'cat': {
+                    const node = await client.group.fs.stat(ref);
+                    const size = numberFrom(node, ['size', 'size_bytes', 'bytes']);
+                    const maxBytes = Math.min(command.maxBytes ?? MAX_MANAGED_FS_CAT_BYTES, MAX_MANAGED_FS_CAT_BYTES);
+                    if (size === undefined)
+                        throw new ManagedFsOperationError('FS_SIZE_REQUIRED', 'group file size is required before managed cat');
+                    if (size > maxBytes)
+                        throw new ManagedFsOperationError('FS_CAT_TOO_LARGE', `managed cat is limited to ${maxBytes} bytes`);
+                    const bytes = bytesFromDownload(await client.group.fs.cp(ref, { kind: 'blob' }, { verifyHash: true }));
+                    if (bytes.byteLength > maxBytes)
+                        throw new ManagedFsOperationError('FS_CAT_TOO_LARGE', `managed cat is limited to ${maxBytes} bytes`);
+                    const headBytes = Math.min(command.headBytes ?? 256, MAX_MANAGED_FS_HEAD_BYTES, bytes.byteLength);
+                    if (bytes.subarray(0, Math.min(bytes.byteLength, 8192)).some(byte => byte === 0)) {
+                        return {
+                            ok: true,
+                            command: 'cat',
+                            path: ref,
+                            size: bytes.byteLength,
+                            binary: true,
+                            head: { encoding: 'base64', bytes: headBytes, data: Buffer.from(bytes.subarray(0, headBytes)).toString('base64') },
+                        };
+                    }
+                    let text;
+                    try {
+                        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+                    }
+                    catch {
+                        throw new ManagedFsOperationError('FS_NOT_UTF8', 'managed cat only returns UTF-8 text or a bounded binary head');
+                    }
+                    return { ok: true, command: 'cat', path: ref, size: bytes.byteLength, binary: false, text };
+                }
+            }
+        });
+    }
+    catch (error) {
+        if (error instanceof ManagedFsOperationError)
+            throw error;
+        throw new ManagedFsOperationError('FS_OPERATION_FAILED', error instanceof Error ? error.message : String(error));
+    }
+}