ec-web 0.0.20 → 0.0.22

package/dist/sources/role-definitions.js

@@ -14,23 +14,23 @@
 import { getModelCatalogSnapshot } from './models.js';
 import { resolveParentDistModule, toFileUrl } from './parent-package.js';
 import { resolvePaths } from '../paths.js';
-import { ipcQuery } from '../ipc-client.js';
+import crypto from 'node:crypto';
 // 动态导入 evolcore 主项目的角色配置模块
 async function getRolesModule() {
     const rolesPath = resolveParentDistModule('config', 'roles.js');
     const cmPath = resolveParentDistModule('config', 'config-manager.js');
     const resolverPath = resolveParentDistModule('config', 'peer-role-resolver.js');
+    const roleServicePath = resolveParentDistModule('config', 'role-service.js');
     const authPath = resolveParentDistModule('core', 'auth', 'auth-gateway.js');
     // Windows 上需要转换为 file:// URL
     try {
         const rolesMod = await import(toFileUrl(rolesPath));
         const cmMod = await import(toFileUrl(cmPath));
         const resolverMod = await import(toFileUrl(resolverPath));
+        const roleServiceMod = await import(toFileUrl(roleServicePath));
         const authMod = await import(toFileUrl(authPath));
         if (!rolesMod.readRolesConfig)
             throw new Error('readRolesConfig not found in roles.js');
-        if (!rolesMod.getBuiltinRolesConfig)
-            throw new Error('getBuiltinRolesConfig not found in roles.js');
         if (!rolesMod.roleExists)
             throw new Error('roleExists not found in roles.js');
         if (!cmMod.read)
@@ -43,9 +43,13 @@ async function getRolesModule() {
             throw new Error('buildAuthSubject not found in auth-gateway.js');
         if (!authMod.authorizeOperation)
             throw new Error('authorizeOperation not found in auth-gateway.js');
+        if (!roleServiceMod.readRoleRegistry || !roleServiceMod.writeRoleRegistry
+            || !roleServiceMod.readRoleDefinition || !roleServiceMod.writeRoleDefinition
+            || !roleServiceMod.registerRole || !roleServiceMod.unregisterRole
+            || !roleServiceMod.resetRoleDefinition)
+            throw new Error('role-service exports are incomplete');
         return {
             readRolesConfig: rolesMod.readRolesConfig,
-            getBuiltinRolesConfig: rolesMod.getBuiltinRolesConfig,
             roleExists: rolesMod.roleExists,
             read: cmMod.read,
             write: cmMod.write,
@@ -53,6 +57,7 @@ async function getRolesModule() {
             resolver: resolverMod,
             buildAuthSubject: authMod.buildAuthSubject,
             authorizeOperation: authMod.authorizeOperation,
+            roleService: roleServiceMod,
         };
     }
     catch (err) {
@@ -78,78 +83,19 @@ async function getOperationRegistryModule() {
         listOperations: mod.listOperations,
     };
 }
-async function execRoleMenu(aid, payload, auth) {
-    const response = await ipcQuery(resolvePaths().socket, {
-        type: 'menu.exec',
-        payload: { ...payload, name: 'role', agent: aid, args: { self: aid, ...(payload.args ?? {}) } },
-        auth: { source: 'ecweb', actorAid: auth.actorAid ?? null, localDirect: !!auth.localDirect },
-    }, 10_000);
-    if (!response?.ok || !response.response)
-        throw new Error(response?.error || 'Role Menu is unavailable');
-    return response.response;
-}
-function roleMenuHttpStatus(code) {
-    if (code === 'NOT_FOUND')
-        return 404;
-    if (code === 'CONFLICT')
-        return 409;
-    if (code === 'PERMISSION_DENIED' || code === 'NOT_ALLOWED')
-        return 403;
-    if (code === 'TEMPORARILY_UNAVAILABLE')
-        return 503;
-    return 400;
-}
-function sendRoleMenuError(res, response) {
-    const error = response?.error ?? { code: 'INTERNAL_ERROR', message: 'Role Menu request failed' };
-    sendJson(res, roleMenuHttpStatus(error.code), {
-        error: error.message,
-        code: error.code,
-        data: error.data,
-    });
-}
-async function rolePolicyRevision(aid, auth) {
-    const response = await execRoleMenu(aid, {
-        type: 'menu.query', id: `ecweb-role-revision-${Date.now()}`,
-        args: { view: 'defaults' },
-    }, auth);
-    if (response.error)
-        throw Object.assign(new Error(response.error.message), { menuResponse: response });
-    return response.data.policyRevision;
+function ecwebAuditContext(auth, aid, operation) {
+    return {
+        ecwebRequestId: auth.ecwebRequestId ?? crypto.randomUUID(),
+        targetAgentAid: aid,
+        endpoint: auth.endpoint ?? 'ECWeb role policy',
+        logicalToolName: operation,
+    };
 }
 export function visibleRoleDefinitionOptions(roleOptions) {
     return roleOptions
         .filter(item => item?.kind === 'user' || item?.value === 'admin')
         .sort((left, right) => Number(right.value === 'admin') - Number(left.value === 'admin'));
 }
-async function buildMenuSnapshot(aid, agents, auth) {
-    const [roleOptions, defaults] = await Promise.all([
-        execRoleMenu(aid, { type: 'menu.options', id: `ecweb-role-options-${Date.now()}`, args: { option: 'roles' } }, auth),
-        execRoleMenu(aid, { type: 'menu.query', id: `ecweb-role-defaults-${Date.now()}`, args: { view: 'defaults' } }, auth),
-    ]);
-    if (roleOptions.error)
-        throw Object.assign(new Error(roleOptions.error.message), { menuResponse: roleOptions });
-    if (defaults.error)
-        throw Object.assign(new Error(defaults.error.message), { menuResponse: defaults });
-    const visibleRoles = visibleRoleDefinitionOptions(roleOptions.data);
-    const details = await Promise.all(visibleRoles.map(item => execRoleMenu(aid, {
-        type: 'menu.query', id: `ecweb-role-${item.value}-${Date.now()}`,
-        args: { view: 'role', roleId: item.value },
-    }, auth)));
-    const roles = {};
-    for (const detail of details) {
-        if (!detail.error)
-            roles[detail.data.roleId] = detail.data.definition;
-    }
-    return {
-        $schema_version: 1,
-        aid,
-        self: aid,
-        agents: summarizeAgents(agents),
-        defaultRoles: defaults.data.defaultRoles,
-        policyRevision: defaults.data.policyRevision,
-        roles,
-    };
-}
 function isWriteMethod(method) {
     return method === 'PUT' || method === 'POST' || method === 'DELETE';
 }
@@ -160,9 +106,10 @@ async function authorizeRolePolicyOperation(modules, processConfig, auth, aid, o
     const actor = auth.actorAid || '';
     const processOwners = Array.isArray(processConfig?.owners) ? processConfig.owners.map(String) : [];
     const syntheticOwner = !!auth.localDirect || (!!actor && processOwners.includes(actor));
+    const actorId = auth.localDirect ? 'local-direct' : actor || undefined;
     const subject = modules.buildAuthSubject({
         selfAid: aid,
-        actorId: auth.localDirect ? 'local-direct' : actor || undefined,
+        actorId,
         channel: `ecweb#${aid}`,
         channelType: 'aun',
         channelId: actor || 'ecweb',
@@ -176,6 +123,19 @@ async function authorizeRolePolicyOperation(modules, processConfig, auth, aid, o
                 isAuthenticated: true,
                 allowAccess: true,
                 roleExists: true,
+                // buildAuthSubject uses the authenticated actor separately from the
+                // resolved relation role to determine daemon-owner provenance.
+                actor: {
+                    operatorId: actorId || 'ecweb',
+                    operatorChannelKey: `ecweb#${aid}`,
+                    operatorChannelType: 'aun',
+                    ...(actor ? {
+                        principalId: actor,
+                        principalStatus: 'native_aid',
+                    } : {
+                        principalStatus: 'unmapped',
+                    }),
+                },
             },
         } : {}),
     });
@@ -191,8 +151,18 @@ async function authorizeRolePolicyOperation(modules, processConfig, auth, aid, o
                 ...args,
             },
         },
+        auditMetadata: ecwebAuditContext(auth, aid, operation),
     });
 }
+function isDaemonOwnerAuth(processConfig, auth) {
+    if (auth.localDirect)
+        return true;
+    const actor = typeof auth.actorAid === 'string' ? auth.actorAid.trim() : '';
+    const processOwners = Array.isArray(processConfig?.owners)
+        ? processConfig.owners.map((value) => String(value || '').trim()).filter(Boolean)
+        : [];
+    return !!actor && processOwners.includes(actor);
+}
 const MODEL_PERMISSION_FIELD = 'baseagents.claude.model';
 const MODEL_PATTERN_OPTIONS = ['*', 'claude-opus-*', 'claude-sonnet-*', 'claude-haiku-*'];
 const COMMAND_PERMISSION_SCOPES = new Set(['relation', 'role', 'agent', 'process', 'filesystem', 'control', 'raw-cli']);
@@ -313,33 +283,24 @@ function isReservedRoleName(roleName) {
 function isValidUserRoleName(roleName) {
     return /^[a-z0-9_-]+$/.test(roleName) && !isReservedRoleName(roleName);
 }
-function builtinUserRoles(modules) {
-    return new Set(Object.keys(modules.getBuiltinRolesConfig().roles || {}));
-}
-function readAgentConfig(modules, aid) {
-    return modules.read(modules.ConfigTarget.Agent, { self: aid }) || { aid, channels: [] };
-}
-function writeAgentConfig(modules, aid, config) {
-    modules.write(modules.ConfigTarget.Agent, { ...config, aid, channels: Array.isArray(config.channels) ? config.channels : [] }, { self: aid });
-}
-function getAgentRoleDefinitions(config) {
-    return config.roles?.definitions && typeof config.roles.definitions === 'object'
-        ? config.roles.definitions
-        : {};
+function writeRoleRegistry(modules, aid, defaultRoles) {
+    const registry = modules.roleService.readRoleRegistry(aid);
+    modules.roleService.writeRoleRegistry(aid, {
+        ...registry,
+        defaultRoles: {
+            private: defaultRoles.private ?? null,
+            group: defaultRoles.group ?? null,
+        },
+    });
 }
-function updateAgentRoles(modules, aid, updater) {
-    const config = readAgentConfig(modules, aid);
-    const roles = config.roles && typeof config.roles === 'object' ? { ...config.roles } : {};
-    if (roles.definitions && typeof roles.definitions === 'object') {
-        roles.definitions = { ...roles.definitions };
+function writeRoleDefinition(modules, aid, roleName, definition) {
+    const registry = modules.roleService.readRoleRegistry(aid);
+    if (!registry.roles.includes(roleName)) {
+        modules.roleService.registerRole(aid, roleName, definition);
     }
-    if (roles.defaultRoles && typeof roles.defaultRoles === 'object') {
-        roles.defaultRoles = { ...roles.defaultRoles };
+    else {
+        modules.roleService.writeRoleDefinition(aid, roleName, definition);
     }
-    updater(roles, config);
-    const next = { ...config, roles };
-    writeAgentConfig(modules, aid, next);
-    return next;
 }
 function normalizeDefaultRoleInput(value, current) {
     if (value === null || value === '')
@@ -623,11 +584,42 @@ async function buildModelPermissionResponse(roleName, roleDef, override) {
 }
 async function buildSnapshot(params = {}, auth = {}) {
     try {
+        auth = {
+            ...auth,
+            ecwebRequestId: params.__ecwebRequestId ?? auth.ecwebRequestId ?? crypto.randomUUID(),
+            endpoint: params.__ecwebEndpoint ?? auth.endpoint ?? 'WS snapshot:roleDefinitions',
+        };
         const agents = await getAgentsFromIpc();
         const aid = resolveRequestedAid(params.aid, agents);
         if (!aid)
             return { $schema_version: 1, aid: null, agents: [], roles: {}, defaultRoles: { private: null, group: null } };
-        return await buildMenuSnapshot(aid, agents, auth);
+        const modules = await getRolesModule();
+        const processConfig = modules.read(modules.ConfigTarget.Process) || {};
+        const decision = await authorizeRolePolicyOperation(modules, processConfig, auth, aid, 'role.policy.read', {
+            method: 'GET',
+            path: '/api/role-definitions',
+        });
+        if (!decision.allow) {
+            return {
+                $schema_version: 1,
+                aid,
+                agents: summarizeAgents(agents),
+                roles: {},
+                defaultRoles: { private: null, group: null },
+                error: decision.reason || 'forbidden: role policy read not allowed',
+                code: decision.code,
+            };
+        }
+        const config = modules.readRolesConfig(aid);
+        return {
+            $schema_version: 1,
+            aid,
+            self: aid,
+            agents: summarizeAgents(agents),
+            defaultRoles: config.defaultRoles ?? { private: null, group: null },
+            policyRevision: JSON.stringify(config),
+            roles: config.roles ?? {},
+        };
     }
     catch (err) {
         console.error('[role-definitions] Failed to build snapshot:', err);
@@ -637,204 +629,30 @@ async function buildSnapshot(params = {}, auth = {}) {
 export const roleDefinitionsSource = {
     kind: 'roleDefinitions',
     async snapshot(params = {}) {
-        return buildSnapshot(params, params.__menuAuth ?? {});
+        return buildSnapshot(params, {
+            ...(params.__menuAuth ?? {}),
+            ecwebRequestId: params.__ecwebRequestId,
+            endpoint: params.__ecwebEndpoint,
+        });
     },
     subscribe(_params, _push) {
         return () => { };
     }
 };
-async function handleRoleMenuCompatibility(req, res, auth, aid, agents, parsedUrl) {
-    const urlPath = parsedUrl.path;
-    const roleRoute = urlPath.match(/^\/api\/role-definitions\/([^/]+)$/);
-    const roleNestedRoute = urlPath.match(/^\/api\/role-definitions\/([^/]+)\/([^/]+)$/);
-    const decodeRole = (raw) => {
-        try {
-            return decodeURIComponent(raw);
-        }
-        catch {
-            return raw;
-        }
-    };
-    const requireAid = () => {
-        if (aid)
-            return true;
-        sendJson(res, 400, { error: 'aid is required' });
-        return false;
-    };
-    const execute = async (payload, successStatus = 200) => {
-        const response = await execRoleMenu(aid, payload, auth);
-        if (response.error) {
-            sendRoleMenuError(res, response);
-            return null;
-        }
-        if (successStatus > 0)
-            sendJson(res, successStatus, response.data);
-        return response.data;
-    };
-    try {
-        if (req.method === 'GET' && urlPath === '/api/role-definitions') {
-            if (!requireAid())
-                return true;
-            try {
-                sendJson(res, 200, await buildMenuSnapshot(aid, agents, auth));
-            }
-            catch (error) {
-                if (error?.menuResponse)
-                    sendRoleMenuError(res, error.menuResponse);
-                else
-                    throw error;
-            }
-            return true;
-        }
-        if (req.method === 'GET' && urlPath === '/api/role-definitions/operations') {
-            if (!requireAid())
-                return true;
-            const data = await execute({
-                type: 'menu.options', id: `ecweb-role-operations-${Date.now()}`, args: { option: 'operations' },
-            }, 0);
-            if (data)
-                sendJson(res, 200, { operations: data.map((item) => ({ id: item.value, ...item })) });
-            return true;
-        }
-        if (req.method === 'PUT' && urlPath === '/api/role-definitions') {
-            if (!requireAid())
-                return true;
-            const body = await readJsonBody(req);
-            if (body.roles !== undefined) {
-                sendJson(res, 400, { error: 'Bulk role replacement is not supported; update roles individually' });
-                return true;
-            }
-            const revision = await rolePolicyRevision(aid, auth);
-            const data = await execute({
-                type: 'menu.update', id: `ecweb-role-defaults-update-${Date.now()}`,
-                args: { resource: 'defaultRoles', expectedPolicyRevision: revision },
-                value: JSON.stringify(body.defaultRoles ?? {}),
-            }, 0);
-            if (data)
-                sendJson(res, 200, { ok: true, data: await buildMenuSnapshot(aid, agents, auth) });
-            return true;
-        }
-        if (req.method === 'POST' && urlPath === '/api/role-definitions') {
-            if (!requireAid())
-                return true;
-            const body = await readJsonBody(req);
-            const { name, ...definition } = body;
-            const revision = await rolePolicyRevision(aid, auth);
-            const data = await execute({
-                type: 'menu.action', id: `ecweb-role-create-${Date.now()}`, action: 'create',
-                args: { roleId: name, definition, expectedPolicyRevision: revision },
-            }, 0);
-            if (data)
-                sendJson(res, 201, { ok: true, role: data.definition, policyRevision: data.policyRevision });
-            return true;
-        }
-        if (req.method === 'GET' && roleRoute) {
-            if (!requireAid())
-                return true;
-            const data = await execute({
-                type: 'menu.query', id: `ecweb-role-detail-${Date.now()}`,
-                args: { view: 'role', roleId: decodeRole(roleRoute[1]) },
-            }, 0);
-            if (data)
-                sendJson(res, 200, data.definition);
-            return true;
-        }
-        if (req.method === 'PUT' && roleRoute) {
-            if (!requireAid())
-                return true;
-            const updates = await readJsonBody(req);
-            const revision = await rolePolicyRevision(aid, auth);
-            const data = await execute({
-                type: 'menu.update', id: `ecweb-role-update-${Date.now()}`,
-                args: { resource: 'definition', roleId: decodeRole(roleRoute[1]), expectedPolicyRevision: revision },
-                value: JSON.stringify(updates),
-            }, 0);
-            if (data)
-                sendJson(res, 200, { ok: true, policyRevision: data.policyRevision });
-            return true;
-        }
-        if (req.method === 'POST' && roleNestedRoute?.[2] === 'reset') {
-            if (!requireAid())
-                return true;
-            const revision = await rolePolicyRevision(aid, auth);
-            const data = await execute({
-                type: 'menu.action', id: `ecweb-role-reset-${Date.now()}`, action: 'reset',
-                args: { roleId: decodeRole(roleNestedRoute[1]), expectedPolicyRevision: revision },
-            }, 0);
-            if (data) {
-                const detail = await execRoleMenu(aid, {
-                    type: 'menu.query', id: `ecweb-role-reset-detail-${Date.now()}`,
-                    args: { view: 'role', roleId: decodeRole(roleNestedRoute[1]) },
-                }, auth);
-                sendJson(res, 200, { ok: true, role: detail.data?.definition, policyRevision: data.policyRevision });
-            }
-            return true;
-        }
-        if (req.method === 'DELETE' && roleRoute) {
-            if (!requireAid())
-                return true;
-            const revision = await rolePolicyRevision(aid, auth);
-            const actionArgs = {
-                roleId: decodeRole(roleRoute[1]),
-                expectedPolicyRevision: revision,
-            };
-            if (Object.prototype.hasOwnProperty.call(parsedUrl.query, 'replacementRoleId')) {
-                actionArgs.replacementRoleId = parsedUrl.query.replacementRoleId || null;
-            }
-            else if (parsedUrl.query.clearReferences === 'true') {
-                actionArgs.replacementRoleId = null;
-            }
-            const data = await execute({
-                type: 'menu.action', id: `ecweb-role-delete-${Date.now()}`, action: 'delete', args: actionArgs,
-            }, 0);
-            if (data)
-                sendJson(res, 200, { ok: true, ...data });
-            return true;
-        }
-        if (req.method === 'PUT' && roleNestedRoute?.[2] === 'model-permissions') {
-            if (!requireAid())
-                return true;
-            const payload = await readJsonBody(req);
-            const revision = await rolePolicyRevision(aid, auth);
-            const permission = {
-                default: payload.defaultModel ?? payload.default,
-                allowOverride: payload.allowOverride === true,
-                allowedModels: Array.isArray(payload.allowedModels) ? payload.allowedModels : [],
-            };
-            const data = await execute({
-                type: 'menu.update', id: `ecweb-role-model-update-${Date.now()}`,
-                args: { resource: 'definition', roleId: decodeRole(roleNestedRoute[1]), expectedPolicyRevision: revision },
-                value: JSON.stringify({ permissions: { [MODEL_PERMISSION_FIELD]: permission } }),
-            }, 0);
-            if (data)
-                sendJson(res, 200, { success: true, data: await buildModelPermissionResponse(decodeRole(roleNestedRoute[1]), data.definition) });
-            return true;
-        }
-    }
-    catch (error) {
-        if (error?.menuResponse)
-            sendRoleMenuError(res, error.menuResponse);
-        else
-            sendJson(res, 500, { error: error?.message || String(error) });
-        return true;
-    }
-    return false;
-}
 // HTTP API handler
 export async function handleRoleDefinitionsApi(req, res, auth = {}) {
     try {
         const parsedUrl = parseUrl(req.url || '');
         const urlPath = parsedUrl.path;
+        auth = {
+            ...auth,
+            ecwebRequestId: auth.ecwebRequestId ?? crypto.randomUUID(),
+            endpoint: auth.endpoint ?? `${req.method ?? 'UNKNOWN'} ${urlPath}`,
+        };
         const agents = await getAgentsFromIpc();
         const aid = resolveRequestedAid(parsedUrl.query.aid, agents);
-        if (await handleRoleMenuCompatibility(req, res, auth, aid, agents, parsedUrl))
-            return;
-        if (isWriteMethod(req.method)) {
-            sendJson(res, 405, { error: 'This Role endpoint is not supported; use Role Menu' });
-            return;
-        }
         const modules = await getRolesModule();
-        const { readRolesConfig, getBuiltinRolesConfig, read, ConfigTarget } = modules;
+        const { readRolesConfig, read, ConfigTarget } = modules;
         const roleRoute = urlPath.match(/^\/api\/role-definitions\/([^/]+)$/);
         const roleNestedRoute = urlPath.match(/^\/api\/role-definitions\/([^/]+)\/([^/]+)$/);
         const decodeRoleName = (raw) => {
@@ -881,9 +699,25 @@ export async function handleRoleDefinitionsApi(req, res, auth = {}) {
                 });
                 return;
             }
+            if (isWriteMethod(req.method) && !isDaemonOwnerAuth(processConfig, auth)
+                && decision.subject?.role === 'admin') {
+                const targetedRole = roleNestedRoute
+                    ? decodeRoleName(roleNestedRoute[1])
+                    : roleRoute
+                        ? decodeRoleName(roleRoute[1])
+                        : null;
+                if (targetedRole === 'owner') {
+                    sendJson(res, 403, {
+                        error: 'forbidden: agent admin cannot modify owner role policy',
+                        code: 'PERMISSION_DENIED',
+                        actorRole: 'admin',
+                    });
+                    return;
+                }
+            }
         }
         if (req.method === 'GET' && urlPath === '/api/role-definitions') {
-            sendJson(res, 200, await buildSnapshot({ aid }));
+            sendJson(res, 200, await buildSnapshot({ aid, __ecwebRequestId: auth.ecwebRequestId, __ecwebEndpoint: auth.endpoint }, auth));
             return;
         }
         if (req.method === 'PUT' && urlPath === '/api/role-definitions') {
@@ -914,22 +748,38 @@ export async function handleRoleDefinitionsApi(req, res, auth = {}) {
                         }
                     }
                 }
-                updateAgentRoles(modules, aid, (roles) => {
-                    if (incoming.defaultRoles && typeof incoming.defaultRoles === 'object') {
-                        roles.defaultRoles = {
-                            private: normalizeDefaultRoleInput(incoming.defaultRoles.private, currentConfig.defaultRoles?.private),
-                            group: normalizeDefaultRoleInput(incoming.defaultRoles.group, currentConfig.defaultRoles?.group),
-                        };
+                if (incoming.roles && typeof incoming.roles === 'object') {
+                    for (const [roleName, roleDef] of Object.entries(incoming.roles)) {
+                        writeRoleDefinition(modules, aid, roleName, normalizeRoleDefinitionForSave(roleDef));
                     }
-                    if (incoming.roles && typeof incoming.roles === 'object') {
-                        const nextDefinitions = {};
-                        for (const [roleName, roleDef] of Object.entries(incoming.roles)) {
-                            nextDefinitions[roleName] = normalizeRoleDefinitionForSave(roleDef);
-                        }
-                        roles.definitions = nextDefinitions;
+                }
+                if (incoming.defaultRoles && typeof incoming.defaultRoles === 'object') {
+                    const nextDefaults = {
+                        private: normalizeDefaultRoleInput(incoming.defaultRoles.private, currentConfig.defaultRoles?.private),
+                        group: normalizeDefaultRoleInput(incoming.defaultRoles.group, currentConfig.defaultRoles?.group),
+                    };
+                    const processConfig = modules.read(modules.ConfigTarget.Process) || {};
+                    const daemonOwner = isDaemonOwnerAuth(processConfig, auth);
+                    const actorRole = daemonOwner
+                        ? 'owner'
+                        : auth.actorAid
+                            ? (modules.resolver.resolvePeerRoleDetail({
+                                selfAid: aid,
+                                channelType: 'aun',
+                                chatType: 'private',
+                                actorId: auth.actorAid,
+                                conversationId: auth.actorAid,
+                            }).effectiveRole || 'none')
+                            : 'none';
+                    const changesAdminDefault = ['private', 'group'].some(scene => currentConfig.defaultRoles?.[scene] !== nextDefaults[scene]
+                        && (currentConfig.defaultRoles?.[scene] === 'admin' || nextDefaults[scene] === 'admin'));
+                    if (!daemonOwner && actorRole !== 'owner' && changesAdminDefault) {
+                        sendJson(res, 403, { error: 'Only an owner can set or replace an admin default role' });
+                        return;
                     }
-                });
-                sendJson(res, 200, { ok: true, data: await buildSnapshot({ aid }) });
+                    writeRoleRegistry(modules, aid, nextDefaults);
+                }
+                sendJson(res, 200, { ok: true, data: await buildSnapshot({ aid, __ecwebRequestId: auth.ecwebRequestId, __ecwebEndpoint: auth.endpoint }, auth) });
             }
             catch (err) {
                 console.error('[role-definitions] Failed to update agent role config:', err);
@@ -975,9 +825,7 @@ export async function handleRoleDefinitionsApi(req, res, auth = {}) {
                 if (usageLimits !== undefined) {
                     newRole.usageLimits = normalizeRoleUsageLimits(usageLimits);
                 }
-                updateAgentRoles(modules, aid, (roles) => {
-                    roles.definitions = { ...(roles.definitions || {}), [name]: newRole };
-                });
+                modules.roleService.registerRole(aid, name, newRole);
                 sendJson(res, 201, { ok: true, role: newRole });
             }
             catch (err) {
@@ -1042,30 +890,19 @@ export async function handleRoleDefinitionsApi(req, res, auth = {}) {
                 allowOverride: validation.value.allowOverride,
                 allowedModels: validation.value.allowedModels,
             };
-            updateAgentRoles(modules, aid, (roles) => {
-                roles.definitions = { ...(roles.definitions || {}), [roleName]: roleDef };
-            });
+            modules.roleService.writeRoleDefinition(aid, roleName, roleDef);
             const data = await buildModelPermissionResponse(roleName, roleDef, validation.value);
             sendJson(res, 200, { success: true, data });
             return;
         }
         if (req.method === 'POST' && roleNestedRoute?.[2] === 'reset') {
             const roleName = decodeRoleName(roleNestedRoute[1]);
-            const builtinConfig = getBuiltinRolesConfig();
-            const builtinRole = builtinConfig.roles[roleName];
-            if (!builtinRole) {
-                sendJson(res, 404, { error: 'Role not found in builtin config' });
+            if (!['admin', 'member', 'visitor'].includes(roleName)) {
+                sendJson(res, 403, { error: 'Only builtin role overrides can be reset' });
                 return;
             }
-            updateAgentRoles(modules, aid, (roles) => {
-                const definitions = { ...(roles.definitions || {}) };
-                delete definitions[roleName];
-                if (Object.keys(definitions).length)
-                    roles.definitions = definitions;
-                else
-                    delete roles.definitions;
-            });
-            sendJson(res, 200, { ok: true, role: builtinRole });
+            modules.roleService.resetRoleDefinition(aid, roleName);
+            sendJson(res, 200, { ok: true, role: readRolesConfig(aid).roles[roleName] });
             return;
         }
         if (req.method === 'GET' && roleRoute) {
@@ -1081,25 +918,21 @@ export async function handleRoleDefinitionsApi(req, res, auth = {}) {
         }
         if (req.method === 'DELETE' && roleRoute) {
             const roleName = decodeRoleName(roleRoute[1]);
-            const builtinRoles = builtinUserRoles(modules);
-            if (builtinRoles.has(roleName) || isReservedRoleName(roleName)) {
+            if (['owner', 'admin', 'member', 'visitor'].includes(roleName)) {
                 sendJson(res, 403, { error: 'Cannot delete builtin or management role' });
                 return;
             }
-            const agentConfig = readAgentConfig(modules, aid);
-            const definitions = getAgentRoleDefinitions(agentConfig);
-            if (!definitions[roleName]) {
+            const config = readRolesConfig(aid);
+            if (!config.roles[roleName]) {
                 sendJson(res, 404, { error: 'Role not found' });
                 return;
             }
-            updateAgentRoles(modules, aid, (roles) => {
-                const nextDefinitions = { ...(roles.definitions || {}) };
-                delete nextDefinitions[roleName];
-                if (Object.keys(nextDefinitions).length)
-                    roles.definitions = nextDefinitions;
-                else
-                    delete roles.definitions;
-            });
+            const replacement = Object.prototype.hasOwnProperty.call(parsedUrl.query, 'replacementRoleId')
+                ? (parsedUrl.query.replacementRoleId || null)
+                : parsedUrl.query.clearReferences === 'true'
+                    ? null
+                    : undefined;
+            modules.roleService.unregisterRole(aid, roleName, replacement);
             sendJson(res, 200, { ok: true });
             return;
         }
@@ -1157,9 +990,7 @@ export async function handleRoleDefinitionsApi(req, res, auth = {}) {
                     sendJson(res, 400, { error: 'Invalid model permissions', errors: validation.errors });
                     return;
                 }
-                updateAgentRoles(modules, aid, (roles) => {
-                    roles.definitions = { ...(roles.definitions || {}), [roleName]: nextRole };
-                });
+                modules.roleService.writeRoleDefinition(aid, roleName, nextRole);
                 sendJson(res, 200, { ok: true });
             }
             catch (err) {