evolcore 0.0.26 → 0.0.28

package/dist/core/command/command-handler.js

@@ -1,5 +1,8 @@
 import { BaseagentRunnerUnavailableError } from '../../agents/runner-types.js';
+import { loadedBaseagentIds } from '../../agents/baseagent-availability.js';
+import { closeDiagnosticSession, diagnosticTokenHash, isDiagnosticSessionActive } from './diag-service.js';
 import { parseMenuClientArgs } from '../../cli/menu-client.js';
+import { ensureSessionRuntimeDir } from '../../cli/task-context.js';
 import { renderCommandCardAsText } from '../interaction-router.js';
 import { buildEnvelope, deliveryTargetFromSession, isInteractionSendAccepted, replyContextFromSession, sendInteractionPayload } from '../message/message-utils.js';
 import { resolvePaths, getPackageRoot } from '../../paths.js';
@@ -8,6 +11,7 @@ import { logger } from '../../utils/logger.js';
 import { resolvePeerRoleDetail, roleToSessionIdentity } from '../../config/peer-role-resolver.js';
 import { isManagementRole } from '../../config/builtin-roles.js';
 import { formatPeerKey } from '../relation/peer-identity.js';
+import { sameGroupAid } from '../../aun/group/index.js';
 import crypto from 'crypto';
 import path from 'path';
 import fs from 'fs';
@@ -24,7 +28,7 @@ import { auditCommandAuthorization, auditFullAccessEvent, hashArgv } from '../au
 import { executeResolvedContactCommand, resolveContactCommand } from '../../config/contact-operation-service.js';
 import { hasTrustedFullAccessDelegation, trustedExecutionIdentityInput } from '../auth/agent-delegation.js';
 import { executeManagedAidOperation, ManagedAidOperationError, managedAidShowViewForRole, resolveManagedAidOperation, } from '../../aun/aid/managed-operation.js';
-import { executeManagedGroupOperation, isManagedGroupRelationRead, ManagedGroupOperationError, resolveManagedGroupOperation, executeManagedMsgOperation, ManagedMsgOperationError, resolveManagedMsgOperation, executeManagedFsOperation, ManagedFsOperationError, resolveManagedFsOperation, } from '../../aun/msg/managed-operation.js';
+import { executeManagedGroupOperation, isManagedGroupRelationRead, isManagedGroupRelationWrite, ManagedGroupOperationError, resolveManagedGroupOperation, executeManagedMsgOperation, ManagedMsgOperationError, resolveManagedMsgOperation, executeManagedFsOperation, ManagedFsOperationError, resolveManagedFsOperation, } from '../../aun/msg/managed-operation.js';
 import { authorizeOperation, buildAuthSubject } from '../auth/auth-gateway.js';
 import { isHClassPath, isLClassPath, isSameOrDescendant } from '../permission/protected-paths.js';
 import { validateModelSelectionForRole } from '../model/model-permission.js';
@@ -99,6 +103,14 @@ export class CommandHandler {
     sessionManager;
     messageCache;
     eventBus;
+    agentStorageClientResolver;
+    groupInviteDecisionResolver;
+    setAgentStorageClientResolver(resolver) {
+        this.agentStorageClientResolver = resolver;
+    }
+    setGroupInviteDecisionResolver(resolver) {
+        this.groupInviteDecisionResolver = resolver;
+    }
     adapters = new Map();
     policies = new Map();
     channelObjects = new Map(); // name → actual channel instance (for /check)
@@ -155,7 +167,34 @@ export class CommandHandler {
                     throw new Error('Menu request file must be a regular file of at most 128 KiB');
                 return fs.readFileSync(target, 'utf8');
             });
-            return { ok: true, response: await send(options) };
+            const binding = session.metadata?.diagnostic;
+            if (binding || session.metadata?.diagnosticStatus === 'cancelled') {
+                if (!isDiagnosticSessionActive(session, this.sessionManager.getChatDir(session))) {
+                    return { ok: false, code: 'DIAG_CLOSED', error: '诊断授权已结束，禁止旧会话继续访问' };
+                }
+                if (binding && (options.targetAid !== binding.controlAid
+                    || diagnosticTokenHash(options.remoteAccessToken ?? options.ecwebToken ?? '') !== binding.tokenHash)) {
+                    return { ok: false, code: 'DIAG_SCOPE_MISMATCH', error: '诊断请求必须使用本会话绑定的主机和 Token' };
+                }
+            }
+            const guardedOptions = binding
+                ? {
+                    ...options,
+                    beforeSend: () => {
+                        if (!isDiagnosticSessionActive(session, this.sessionManager.getChatDir(session))) {
+                            const error = new Error('诊断授权已结束，禁止旧会话继续访问');
+                            error.code = 'DIAG_CLOSED';
+                            throw error;
+                        }
+                    },
+                }
+                : options;
+            const response = await send(guardedOptions);
+            if (binding && response?.error?.code === 'REMOTE_ACCESS_TOKEN_INVALID') {
+                closeDiagnosticSession(session, this.sessionManager.getChatDir(session));
+                this.messageQueue?.clearBySession(session.id);
+            }
+            return { ok: true, response };
         }
         catch (error) {
             return { ok: false, code: error.code ?? 'MENU_REQUEST_FAILED', error: error.message };
@@ -208,19 +247,11 @@ export class CommandHandler {
         throw new BaseagentRunnerUnavailableError('<unknown>', requestedBaseagent || '<missing>', []);
     }
     getAvailableBaseagentsForOwner(evolName) {
-        const prefix = `${evolName}::`;
-        return [...this.agentMap.keys()]
-            .filter(key => key.startsWith(prefix))
-            .map(key => key.slice(prefix.length));
+        return loadedBaseagentIds(this.agentMap.keys(), evolName);
     }
-    /** Return the runner-owned temporary root for a managed session, if any. */
+    /** Return the stable temporary root for a managed session, if available. */
     getManagedSessionTempDir(session) {
-        try {
-            return this.getAgent(session.channel, session.baseagent).getManagedTempDir?.(session.id);
-        }
-        catch {
-            return undefined;
-        }
+        return ensureSessionRuntimeDir(session.id);
     }
     formatBaseagentUnavailable(error) {
         const available = error.availableBaseagents.length ? error.availableBaseagents.join(', ') : '(none)';
@@ -236,21 +267,10 @@ export class CommandHandler {
     getAvailableBaseagents(channel) {
         const owner = this.agentRegistry?.resolveByChannel(channel);
         if (!owner) {
-            const result = new Set();
-            for (const key of this.agentMap.keys()) {
-                const idx = key.indexOf('::');
-                result.add(idx >= 0 ? key.slice(idx + 2) : key);
-            }
-            return [...result];
+            return loadedBaseagentIds(this.agentMap.keys());
         }
         const evolName = owner.name || '<unknown>';
-        const prefix = `${evolName}::`;
-        const result = [];
-        for (const key of this.agentMap.keys()) {
-            if (key.startsWith(prefix))
-                result.push(key.slice(prefix.length));
-        }
-        return result;
+        return loadedBaseagentIds(this.agentMap.keys(), evolName);
     }
     /** Extract the baseagent component from `primaryRunnerKey` (e.g. `aid::claude` → `claude`). */
     parseDefaultBaseagent() {
@@ -441,6 +461,8 @@ export class CommandHandler {
     primaryFeedbackTarget(definition) {
         if (definition.feedback.strategy === 'target')
             return definition.feedback.target;
+        if (definition.feedback.strategy === 'event_session')
+            return undefined;
         if (!definition.origin)
             return undefined;
         return {
@@ -625,10 +647,16 @@ export class CommandHandler {
         if (!isAdmin && parsed.feedbackStrategy === 'target' && !sameFeedbackTarget(target, origin)) {
             return { error: '无权限：非 admin 只能把 trigger 投递到来源会话' };
         }
+        if (!isAdmin && parsed.feedbackStrategy === 'event_session') {
+            return { error: '无权限：只有 owner/admin 可以使用事件来源会话' };
+        }
         const source = this.triggerSourceFromSchedule(parsed.scheduleType, parsed.scheduleValue);
         if (parsed.timezone && source.type === 'cron') {
             source.timezone = parsed.timezone;
         }
+        if (parsed.eventFilter !== undefined && source.type === 'event') {
+            source.filter = parsed.eventFilter;
+        }
         const script = parsed.scriptPath ? {
             path: parsed.scriptPath,
             runtime: parsed.scriptRuntime,
@@ -688,6 +716,7 @@ export class CommandHandler {
                     baseagent: executionBaseagent,
                 } : {}),
                 model: parsed.model,
+                timeoutMs: parsed.executionTimeoutMs,
                 effort: parsed.effort,
                 ...(permissionMode !== undefined ? { permissionMode } : {}),
                 onError: 'retry',
@@ -847,23 +876,36 @@ export class CommandHandler {
      * 通用降级应答入口：按 (sessionId, fallbackCommand) 查找 pending interaction 并路由。
      * 返回 { matched: true } 表示已处理，调用方直接返回 result。
      */
-    async handleInteractionFallback(command, args, sessionId, userId) {
+    async handleInteractionFallback(command, args, sessionId, userId, channelKey) {
         if (!this.interactionRouter)
             return { matched: false };
-        const pendingId = this.interactionRouter.findPendingByCommand(sessionId, command);
+        const candidates = this.interactionRouter.getPending(sessionId, command);
+        const explicitId = args.split(/\s+/, 1)[0];
+        if (explicitId.startsWith('aq-') && !candidates.includes(explicitId)) {
+            return { matched: true, result: '⚠️ 该问题不存在、已回答或已过期，请使用当前问题卡片。' };
+        }
+        const pendingId = candidates.includes(explicitId)
+            ? explicitId : this.interactionRouter.findPendingByCommand(sessionId, command);
         if (!pendingId)
             return { matched: false };
+        if (explicitId !== pendingId && candidates.length > 1) {
+            return { matched: true, result: `有多个待回答问题，请使用 /ask <问题ID> <回答>：\n${candidates.join('\n')}` };
+        }
+        const answer = explicitId === pendingId ? args.slice(explicitId.length).trim() : args.trim();
+        if (!answer)
+            return { matched: true, result: `请使用 /ask ${pendingId} <回答>` };
         const initiatorId = this.interactionRouter.getInitiator(pendingId);
         if (initiatorId && initiatorId !== userId) {
             return { matched: true, result: '⚠️ 仅卡片发起者可应答' };
         }
-        const handled = this.interactionRouter.handle({
+        const handled = await this.interactionRouter.handleAsync({
             type: 'interaction.response',
             id: pendingId,
-            action: args,
+            action: answer,
             operatorId: userId,
+            ...(channelKey ? { channelKey } : {}),
         });
-        return { matched: true, result: handled ? '✓ 已回答' : '⚠️ 无法验证应答者身份' };
+        return { matched: true, result: handled ? '✓ 已回答' : '⚠️ 回答未被接受，请检查选项或问题是否仍有效。' };
     }
     setProcessor(processor) {
         this.processor = processor;
@@ -1003,6 +1045,7 @@ export class CommandHandler {
         const item = {
             value: s.threadId,
             label: displayName,
+            lable: s.lable || null,
         };
         if (s.agentSessionId) {
             item.agentSessionId = s.agentSessionId;
@@ -1031,7 +1074,7 @@ export class CommandHandler {
             ...(paircodeAllowed === undefined ? {} : { paircodeAllowed }),
         });
     }
-    async execMenuValueBatch(channel, channelId, subject, args, request, channelScope = 'agent') {
+    async execMenuValueBatch(channel, channelId, subject, args, request, channelScope = 'agent', transportReplyContext) {
         validateMenuValueBatchArgs(args);
         return await execMenuValueBatch({
             subject,
@@ -1042,12 +1085,12 @@ export class CommandHandler {
             items: args?.items,
             schemaVersion: args?.schemaVersion,
             consistency: args?.consistency,
-            execQuery: async (cmd, resolvedChannelId, queryArgs, context) => this.execMenuQuery(cmd, channel, resolvedChannelId, context.subject.actorId, queryArgs, context.subject.chatType, context.subject.fromControlChannel, context.subject.identity, context.subject, channelScope === 'control' ? 'control' : 'menu'),
+            execQuery: async (cmd, resolvedChannelId, queryArgs, context) => this.execMenuQuery(cmd, channel, resolvedChannelId, context.subject.actorId, queryArgs, context.subject.chatType, context.subject.fromControlChannel, context.subject.identity, context.subject, channelScope === 'control' ? 'control' : 'menu', resolvedChannelId === channelId ? transportReplyContext : undefined),
         });
     }
     /** 动态子菜单：根据 cmd 路径返回选项列表（供 menu.query + cmd 使用） */
-    async getSubMenuItems(cmd, channel, channelId, userId, args, overrideIdentity, explicitChatType, fromControlChannel = false, authSubject, source = 'menu') {
-        return await menuGetSubMenuItems.call(this, cmd, channel, channelId, userId, args, overrideIdentity, explicitChatType, fromControlChannel, authSubject, source);
+    async getSubMenuItems(cmd, channel, channelId, userId, args, overrideIdentity, explicitChatType, fromControlChannel = false, authSubject, source = 'menu', transportReplyContext) {
+        return await menuGetSubMenuItems.call(this, cmd, channel, channelId, userId, args, overrideIdentity, explicitChatType, fromControlChannel, authSubject, source, transportReplyContext);
     }
     // ── Menu Protocol exec ────────────────────────────────────────────────
     async loadMenuContext(channel, channelId) {
@@ -1059,8 +1102,8 @@ export class CommandHandler {
         return s ? null : { error: '当前无活跃会话', code: 'NO_ACTIVE_SESSION' };
     }
     /** menu.query — 查询当前值。 */
-    async execMenuQuery(cmd, channel, channelId, userId, args, explicitChatType, fromControlChannel = false, overrideIdentity, authSubject, source = 'menu') {
-        return await menuExecMenuQuery.call(this, cmd, channel, channelId, userId, args, explicitChatType, fromControlChannel, overrideIdentity, authSubject, source);
+    async execMenuQuery(cmd, channel, channelId, userId, args, explicitChatType, fromControlChannel = false, overrideIdentity, authSubject, source = 'menu', transportReplyContext) {
+        return await menuExecMenuQuery.call(this, cmd, channel, channelId, userId, args, explicitChatType, fromControlChannel, overrideIdentity, authSubject, source, transportReplyContext);
     }
     /** menu.update — 写入新值。 */
     async execMenuUpdate(cmd, value, channel, channelId, userId, overrideIdentity, fromControlChannel = false, args, authSubject, source = 'menu', transportReplyContext) {
@@ -1513,6 +1556,9 @@ export class CommandHandler {
             updated = deescalated;
         }
         const target = this.primaryFeedbackTarget(updated);
+        if (!isAdmin && updated.feedback.strategy === 'event_session') {
+            return { ok: false, error: '无权限：只有 owner/admin 可以使用事件来源会话' };
+        }
         if (!isAdmin && target && !sameFeedbackTarget(target, definition.origin)) {
             return { ok: false, error: '无权限：非 admin 只能把 trigger 投递到来源会话' };
         }
@@ -2181,7 +2227,8 @@ export class CommandHandler {
         const managementRole = isManagementRole(subject.role) || subject.dataScope === 'daemon';
         if (subject.dataScope !== 'daemon'
             && !managementRole
-            && (grant.channelType !== 'aun' || !isManagedGroupRelationRead(parsed.command))) {
+            && (grant.channelType !== 'aun'
+                || !(isManagedGroupRelationRead(parsed.command) || isManagedGroupRelationWrite(parsed.command)))) {
             return { ok: false, code: 'ROLE_ACCESS_DENIED', error: `Role ${subject.role} cannot manage Agent group membership or settings` };
         }
         if ((parsed.command.kind === 'dissolve' || parsed.command.kind === 'owner')
@@ -2213,6 +2260,21 @@ export class CommandHandler {
         });
         if (!decision.allow)
             return { ok: false, code: decision.code, error: decision.reason };
+        if (parsed.command.kind === 'accept-invite' || parsed.command.kind === 'reject-invite') {
+            if (subject.role !== 'owner' || grant.channelType !== 'aun' || grant.chatType !== 'private'
+                || parsed.command.from !== grantSelfAid || !this.groupInviteDecisionResolver) {
+                return { ok: false, code: 'ROLE_ACCESS_DENIED', error: 'Targeted invitation decisions require the current Agent Owner' };
+            }
+            try {
+                const result = await this.groupInviteDecisionResolver(grantSelfAid, grant.actorId, parsed.command.inviteId, parsed.command.kind === 'accept-invite' ? 'accept' : 'reject');
+                return result.accepted
+                    ? { ok: true, result: { ok: true, status: result.status, group_id: result.groupId, message: result.text } }
+                    : { ok: false, code: 'GROUP_INVITE_DECISION_REJECTED', error: result.text };
+            }
+            catch (error) {
+                return { ok: false, code: 'GROUP_INVITE_DECISION_FAILED', error: error instanceof Error ? error.message : String(error) };
+            }
+        }
         let rulesContent;
         if (parsed.command.kind === 'rules.set') {
             const filePath = String(parsed.command.filePath || '');
@@ -2267,7 +2329,10 @@ export class CommandHandler {
             }
         }
         try {
-            return { ok: true, result: await executeManagedGroupOperation(parsed.command, rulesContent) };
+            return { ok: true, result: await executeManagedGroupOperation(parsed.command, rulesContent, {
+                    defaultThread: grant.chatType === 'group' && conversationId === parsed.command.groupId
+                        ? session.threadId || 'main' : 'all',
+                }) };
         }
         catch (error) {
             return {
@@ -2464,7 +2529,7 @@ export class CommandHandler {
             return { ok: false, code: 'INVALID_DELEGATION', error: 'Delegation contains an invalid relation key' };
         }
         if (!hasTrustedFullAccessDelegation(grant)
-            && ((parsed.command.actorAid && parsed.command.actorAid !== actorAid) || parsed.command.groupId !== currentGroup)) {
+            && ((parsed.command.actorAid && parsed.command.actorAid !== actorAid) || !sameGroupAid(parsed.command.groupId, currentGroup))) {
             return { ok: false, code: 'SCOPE_MISMATCH', error: 'Only the current AUN group can be targeted' };
         }
         parsed.command.actorAid = hasTrustedFullAccessDelegation(grant)

package/dist/core/command/data-root-resolver.js

@@ -0,0 +1,273 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { isValidAid } from '../../aun/aid/validation.js';
+import { isExplicitGroupId } from '../../aun/group/index.js';
+import { isStaticAgentOwner } from '../../config/peer-role-resolver.js';
+import { agentDir, agentRelationSharedDir } from '../../paths.js';
+import { formatPeerKey } from '../relation/peer-identity.js';
+export class DataRootError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = 'DataRootError';
+        this.code = code;
+        this.data = data;
+    }
+}
+const DEFAULT_ROOT_TTL_MS = 10 * 60 * 1000;
+const TOKEN_PREFIX = 'dr1';
+function base64Url(value) {
+    return Buffer.from(value).toString('base64url');
+}
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+function authenticatedPrincipal(subject) {
+    const principalId = String(subject.principalId ?? '').trim();
+    if (!isValidAid(principalId) || isExplicitGroupId(principalId)) {
+        throw new DataRootError('ROOT_FORBIDDEN', 'A verified private AUN principal is required');
+    }
+    return principalId;
+}
+export class DataRootResolver {
+    secret;
+    ttlMs;
+    now;
+    isOwner;
+    resolveAgentPath;
+    resolveRelationSharedPath;
+    constructor(options = {}) {
+        this.secret = options.secret ?? crypto.randomBytes(32);
+        if (this.secret.length < 32)
+            throw new Error('Data root signing secret must be at least 32 bytes');
+        this.ttlMs = options.ttlMs ?? DEFAULT_ROOT_TTL_MS;
+        this.now = options.now ?? (() => Date.now());
+        this.isOwner = options.isOwner ?? isStaticAgentOwner;
+        this.resolveAgentPath = options.resolveAgentPath ?? agentDir;
+        this.resolveRelationSharedPath = options.resolveRelationSharedPath ?? agentRelationSharedDir;
+    }
+    issueAgentRoot(subject) {
+        const targetAid = this.targetAid(subject);
+        const principalId = authenticatedPrincipal(subject);
+        if (subject.role !== 'owner' || !this.isOwner(targetAid, principalId)) {
+            throw new DataRootError('ROOT_FORBIDDEN', 'Agent data root requires Agent owner permission');
+        }
+        const rootPath = this.canonicalRoot(this.resolveAgentPath(targetAid), undefined);
+        return this.issueDescriptor({ scope: 'agent', targetAid, principalId }, rootPath);
+    }
+    issueRelationRoot(subject, requestedPeerAid) {
+        const targetAid = this.targetAid(subject);
+        this.assertPrivateAun(subject);
+        const principalId = authenticatedPrincipal(subject);
+        const owner = subject.role === 'owner' && this.isOwner(targetAid, principalId);
+        const explicitPeerAid = typeof requestedPeerAid === 'string' ? requestedPeerAid.trim() : '';
+        if (requestedPeerAid !== undefined && !explicitPeerAid) {
+            throw new DataRootError('INVALID_ARGUMENT', 'args.peerAid must be a non-empty AUN AID');
+        }
+        if (explicitPeerAid && !owner) {
+            throw new DataRootError('ROOT_FORBIDDEN', 'Only the Agent owner may select another relation');
+        }
+        const peerAid = explicitPeerAid || principalId;
+        if (!isValidAid(peerAid) || isExplicitGroupId(peerAid)) {
+            throw new DataRootError('INVALID_ARGUMENT', 'args.peerAid must identify an AUN private-chat peer');
+        }
+        const peerKey = formatPeerKey('aun', peerAid);
+        const agentRoot = this.canonicalRoot(this.resolveAgentPath(targetAid), undefined);
+        const rootPath = this.canonicalRoot(this.resolveRelationSharedPath(targetAid, peerKey), agentRoot);
+        return this.issueDescriptor({ scope: 'relation', targetAid, principalId, peerAid, peerKey }, rootPath);
+    }
+    resolveRoot(rootId, subject) {
+        const claims = this.verifyToken(rootId);
+        const targetAid = this.targetAid(subject);
+        const principalId = authenticatedPrincipal(subject);
+        if (claims.targetAid !== targetAid) {
+            throw new DataRootError('ROOT_SCOPE_MISMATCH', 'Root does not belong to the receiving Agent');
+        }
+        if (claims.principalId !== principalId) {
+            throw new DataRootError('ROOT_FORBIDDEN', 'Root was issued to another authenticated principal');
+        }
+        let rootPath;
+        if (claims.scope === 'agent') {
+            if (subject.role !== 'owner' || !this.isOwner(targetAid, principalId)) {
+                throw new DataRootError('ROOT_FORBIDDEN', 'Agent data root requires Agent owner permission');
+            }
+            rootPath = this.canonicalRoot(this.resolveAgentPath(targetAid), undefined);
+        }
+        else {
+            this.assertPrivateAun(subject);
+            if (!claims.peerAid || !claims.peerKey || claims.peerKey !== formatPeerKey('aun', claims.peerAid)) {
+                throw new DataRootError('ROOT_SCOPE_MISMATCH', 'Relation root claims are invalid');
+            }
+            const owner = subject.role === 'owner' && this.isOwner(targetAid, principalId);
+            if (!owner && principalId !== claims.peerAid) {
+                throw new DataRootError('ROOT_PEER_MISMATCH', 'Only the relation peer may use this root');
+            }
+            const agentRoot = this.canonicalRoot(this.resolveAgentPath(targetAid), undefined);
+            rootPath = this.canonicalRoot(this.resolveRelationSharedPath(targetAid, claims.peerKey), agentRoot);
+        }
+        const revision = this.rootRevision(rootPath);
+        if (revision !== claims.revision) {
+            throw new DataRootError('ROOT_SCOPE_MISMATCH', 'Root identity changed; request a new root');
+        }
+        return {
+            scope: claims.scope,
+            targetAid,
+            ...(claims.peerAid ? { peerAid: claims.peerAid } : {}),
+            ...(claims.peerKey ? { peerKey: claims.peerKey } : {}),
+            rootPath,
+            revision,
+            expiresAt: claims.expiresAt,
+        };
+    }
+    resolvePath(rootId, subject, input, expectType) {
+        const root = this.resolveRoot(rootId, subject);
+        const raw = String(input ?? '').trim();
+        if (!raw)
+            throw new DataRootError('INVALID_ROOT_PATH', 'A root-relative path is required');
+        if (raw.includes('\0'))
+            throw new DataRootError('INVALID_ROOT_PATH', 'NUL is not allowed in a path');
+        if (path.isAbsolute(raw) || path.win32.isAbsolute(raw) || path.posix.isAbsolute(raw)) {
+            throw new DataRootError('INVALID_ROOT_PATH', 'Data root paths must be relative');
+        }
+        if (raw.split(/[\\/]+/).includes('..')) {
+            throw new DataRootError('INVALID_ROOT_PATH', 'Parent traversal is not allowed');
+        }
+        const lexicalPath = path.resolve(root.rootPath, raw);
+        if (!isInside(root.rootPath, lexicalPath)) {
+            throw new DataRootError('INVALID_ROOT_PATH', 'Path escapes the data root');
+        }
+        let realPath;
+        let stat;
+        try {
+            realPath = fs.realpathSync(lexicalPath);
+            stat = fs.statSync(realPath);
+        }
+        catch {
+            throw new DataRootError('NOT_FOUND', 'File or directory does not exist');
+        }
+        if (!isInside(root.rootPath, realPath)) {
+            throw new DataRootError('INVALID_ROOT_PATH', 'Symbolic link escapes the data root');
+        }
+        if (expectType === 'file' && !stat.isFile()) {
+            throw new DataRootError('NOT_SUPPORTED', 'Path is not a regular file');
+        }
+        if (expectType === 'directory' && !stat.isDirectory()) {
+            throw new DataRootError('NOT_A_DIRECTORY', 'Path is not a directory');
+        }
+        const relativePath = path.relative(root.rootPath, realPath).split(path.sep).join('/') || '.';
+        return { ...root, realPath, relativePath, stat };
+    }
+    issueDescriptor(base, rootPath) {
+        const issuedAt = this.now();
+        const claims = {
+            v: 1,
+            ...base,
+            revision: this.rootRevision(rootPath),
+            issuedAt,
+            expiresAt: issuedAt + this.ttlMs,
+            nonce: crypto.randomBytes(12).toString('base64url'),
+        };
+        return {
+            rootId: this.sign(claims),
+            scope: claims.scope,
+            targetAid: claims.targetAid,
+            ...(claims.peerAid ? { peerAid: claims.peerAid } : {}),
+            ...(claims.peerKey ? { peerKey: claims.peerKey } : {}),
+            virtualPath: claims.scope === 'agent'
+                ? '$AGENTS_DIR/<targetAid>'
+                : '$AGENTS_DIR/<targetAid>/relations/<peerKey>/shared',
+            revision: `sha256:${claims.revision}`,
+            expiresAt: claims.expiresAt,
+            readOnly: true,
+            capabilities: { list: true, query: true, fetch: true },
+        };
+    }
+    sign(claims) {
+        const encoded = base64Url(JSON.stringify(claims));
+        const signature = crypto.createHmac('sha256', this.secret).update(encoded).digest('base64url');
+        return `${TOKEN_PREFIX}.${encoded}.${signature}`;
+    }
+    verifyToken(value) {
+        if (typeof value !== 'string' || !value.trim()) {
+            throw new DataRootError('MISSING_ROOT_ID', 'A data rootId is required');
+        }
+        const parts = value.split('.');
+        if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX) {
+            throw new DataRootError('INVALID_ROOT_ID', 'Invalid data rootId');
+        }
+        const expected = crypto.createHmac('sha256', this.secret).update(parts[1]).digest();
+        let actual;
+        try {
+            actual = Buffer.from(parts[2], 'base64url');
+        }
+        catch {
+            throw new DataRootError('INVALID_ROOT_ID', 'Invalid data rootId');
+        }
+        if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
+            throw new DataRootError('INVALID_ROOT_ID', 'Invalid data rootId signature');
+        }
+        let claims;
+        try {
+            claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        }
+        catch {
+            throw new DataRootError('INVALID_ROOT_ID', 'Invalid data rootId payload');
+        }
+        if (claims.v !== 1
+            || (claims.scope !== 'agent' && claims.scope !== 'relation')
+            || typeof claims.targetAid !== 'string'
+            || typeof claims.principalId !== 'string'
+            || typeof claims.revision !== 'string'
+            || !Number.isFinite(claims.expiresAt)) {
+            throw new DataRootError('INVALID_ROOT_ID', 'Invalid data rootId claims');
+        }
+        if (claims.expiresAt <= this.now()) {
+            throw new DataRootError('ROOT_EXPIRED', 'Data rootId expired; query the root again');
+        }
+        return claims;
+    }
+    canonicalRoot(candidate, requiredParent) {
+        let realPath;
+        let stat;
+        try {
+            realPath = fs.realpathSync(candidate);
+            stat = fs.statSync(realPath);
+        }
+        catch {
+            throw new DataRootError('ROOT_NOT_FOUND', 'Data root does not exist');
+        }
+        if (!stat.isDirectory())
+            throw new DataRootError('ROOT_NOT_FOUND', 'Data root is not a directory');
+        if (requiredParent && !isInside(requiredParent, realPath)) {
+            throw new DataRootError('ROOT_SCOPE_MISMATCH', 'Data root escapes the Agent directory');
+        }
+        return realPath;
+    }
+    rootRevision(rootPath) {
+        const stat = fs.statSync(rootPath);
+        return crypto.createHash('sha256')
+            .update(JSON.stringify({ rootPath, dev: stat.dev, ino: stat.ino, birthtimeMs: stat.birthtimeMs }))
+            .digest('hex');
+    }
+    targetAid(subject) {
+        const targetAid = String(subject.selfAid ?? '').trim();
+        if (!isValidAid(targetAid))
+            throw new DataRootError('ROOT_FORBIDDEN', 'Receiving Agent AID is unavailable');
+        return targetAid;
+    }
+    assertPrivateAun(subject) {
+        if (subject.channelType !== 'aun' || subject.chatType !== 'private') {
+            throw new DataRootError('NOT_SUPPORTED', 'Relation data roots currently support AUN private chats only');
+        }
+    }
+}
+export const dataRootResolver = new DataRootResolver();
+export function dataRootFailure(error) {
+    if (error instanceof DataRootError) {
+        return { error: error.message, code: error.code, ...(error.data ? { data: error.data } : {}) };
+    }
+    return { error: 'Internal data root error', code: 'INTERNAL_ERROR' };
+}