evolcore 0.0.1 → 0.0.3

package/dist/config/lifecycle.js

@@ -0,0 +1,17 @@
+import { CONFIG_SCHEMA_VERSION } from '../types.js';
+const VALID_LIFECYCLES = new Set(['created', 'bootstrapping', 'active']);
+export function normalizeAgentLifecycle(config) {
+    const current = config.lifecycle;
+    if (current && VALID_LIFECYCLES.has(current)) {
+        return config;
+    }
+    const lifecycle = config.initialized === true ? 'active'
+        : config.initialized === false ? 'created'
+            : 'active';
+    return { ...config, lifecycle };
+}
+export function withLifecycleForWrite(config, lifecycle) {
+    const next = { ...config, $schema_version: CONFIG_SCHEMA_VERSION, lifecycle };
+    delete next.initialized;
+    return next;
+}

package/dist/config/mention-mode.js

@@ -0,0 +1,27 @@
+/**
+ * mentionMode ↔ AUN 协议 dispatch_mode 词汇翻译（单一事实源）。
+ *
+ * 配置层用 mentionMode（disabled / mention-only），AUN 协议层用 dispatch_mode
+ * （broadcast / mention）。二者语义等价，仅词汇不同：
+ *   - mention-only（只处理被 @ 的消息）≡ mention（仅被 @ 时响应）
+ *   - disabled（关闭 mention 过滤）    ≡ broadcast（全部响应）
+ *
+ * 仅在协议边界（AUN resolver、render fallback）翻译；配置层、命令层一律用
+ * mentionMode 词汇。
+ */
+/** config → AUN 协议词汇；未知/未设值返回 undefined（回退服务端 dispatch_mode）。 */
+export function mentionModeToDispatch(mode) {
+    if (mode === 'mention-only')
+        return 'mention';
+    if (mode === 'disabled')
+        return 'broadcast';
+    return undefined;
+}
+/** AUN 协议词汇 → config；未知返回 undefined。 */
+export function dispatchToMentionMode(dispatch) {
+    if (dispatch === 'mention')
+        return 'mention-only';
+    if (dispatch === 'broadcast')
+        return 'disabled';
+    return undefined;
+}

package/dist/config/merge.js

@@ -0,0 +1,161 @@
+/**
+ * merge —— 类型驱动的覆盖链合并（design §三，全项目唯一实现点）+ ${VAR} 展开。
+ *
+ * 合并三规则（按字段的 x-merge 语义）：
+ *   - scalar：高优先级整体覆盖
+ *   - list：  并集追加去重（只能加，不能减）
+ *   - dict：  键并集；同键 → 高优先级值直接覆盖（**不递归**，合并粒度=第一层键）
+ *
+ * 合并代码永远只有这三条规则；所有"覆盖 vs 追加"通过 schema 的 x-merge 选择表达，不为字段写特判。
+ */
+import fs from 'fs';
+import path from 'path';
+/** list 并集去重——标量元素按值去重；对象元素按 JSON 串去重。 */
+function unionList(base, overlay) {
+    const out = [];
+    const seen = new Set();
+    const keyOf = (v) => (v !== null && typeof v === 'object') ? JSON.stringify(v) : `${typeof v}:${String(v)}`;
+    for (const v of [...base, ...overlay]) {
+        const k = keyOf(v);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(v);
+    }
+    return out;
+}
+/** dict 第一层键合并：键并集，同键高优先级整体覆盖（不递归）。 */
+function mergeDict(base, overlay) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(overlay))
+        out[k] = v;
+    return out;
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * 按 schema 字段表，对覆盖链上"存在的每一级"做类型驱动合并。
+ * layers 从低优先级到高优先级；低优先级独有字段保留，冲突点高优先级胜。
+ * 字段未在 schema 中（理论上 ajv 已拦）按 scalar 处理。
+ */
+export function mergeLayers(layers, fields) {
+    const out = {};
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        for (const [k, v] of Object.entries(layer)) {
+            if (v === undefined)
+                continue;
+            const spec = fields.get(k);
+            const kind = spec?.merge ?? 'scalar';
+            const prev = out[k];
+            if (prev === undefined) {
+                out[k] = v;
+                continue;
+            }
+            if (kind === 'list' && Array.isArray(prev) && Array.isArray(v)) {
+                out[k] = unionList(prev, v);
+            }
+            else if (kind === 'dict' && isPlainObject(prev) && isPlainObject(v)) {
+                out[k] = mergeDict(prev, v);
+            }
+            else {
+                out[k] = v; // scalar 覆盖（或类型不一致时高优先级胜）
+            }
+        }
+    }
+    return out;
+}
+// ── ${VAR} 三级 .env 展开（design §五）─────────────────────────────────────
+//
+// 仅支持 ${VAR}（废弃旧 $ENV:NAME）。解析优先级：
+//   关系级 .env > agent 级 .env > 全局 .env > 进程环境变量
+// 展开只发生在运行时内部消费路径（read 的 expand=true），CLI 读路径不展开。
+const VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+const _warnedVars = new Set();
+/** 解析单个 .env 文件为 KV（极简：KEY=VALUE，忽略注释/空行，去引号）。不存在返回 {}。 */
+function parseEnvFile(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t || t.startsWith('#'))
+            continue;
+        const eq = t.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = t.slice(0, eq).trim();
+        let val = t.slice(eq + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+        }
+        out[key] = val;
+    }
+    return out;
+}
+/**
+ * 构造 ${VAR} 查值器：按 关系 > agent > 全局 > process.env 优先级，首个命中为准。
+ */
+export function buildEnvResolver(scope) {
+    const layers = [];
+    if (scope.relationDir)
+        layers.push(parseEnvFile(path.join(scope.relationDir, '.env')));
+    if (scope.agentDir)
+        layers.push(parseEnvFile(path.join(scope.agentDir, '.env')));
+    if (scope.rootDir)
+        layers.push(parseEnvFile(path.join(scope.rootDir, '.env')));
+    return (name) => {
+        for (const l of layers) {
+            if (Object.prototype.hasOwnProperty.call(l, name))
+                return l[name];
+        }
+        return process.env[name];
+    };
+}
+/**
+ * 递归展开对象中所有 ${VAR} 引用。缺失变量沿用"warn 一次 + 当空字符串"语义。
+ * resolver 缺省（仅 process.env）时也可用。
+ */
+export function expandVars(value, resolve) {
+    return walk(value, resolve);
+}
+function walk(v, resolve) {
+    if (typeof v === 'string') {
+        return v.replace(VAR_RE, (_m, name) => {
+            const got = resolve(name);
+            if (got === undefined) {
+                if (!_warnedVars.has(name)) {
+                    // 延迟 import logger 会引入循环；直接 console.warn（与现有 config 行为一致级别）
+                    console.warn(`[config] env "${name}" not set; \${${name}} expands to empty`);
+                    _warnedVars.add(name);
+                }
+                return '';
+            }
+            return got;
+        });
+    }
+    if (Array.isArray(v))
+        return v.map(x => walk(x, resolve));
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[k] = walk(val, resolve);
+        return out;
+    }
+    return v;
+}
+/** 测试用：复位 warn 去重集。 */
+export function _resetEnvWarnings() {
+    _warnedVars.clear();
+}
+/** 导出供 schema-entry 合并用：从 SchemaEntry 取字段表的便捷封装。 */
+export function fieldsOf(entry) {
+    return entry.fields;
+}

package/dist/config/owner-policy.js

@@ -0,0 +1,4 @@
+export function shouldFailFastForMissingOwners(env = process.env) {
+    const value = (env.EVOLCORE_REQUIRE_OWNERS || '').trim().toLowerCase();
+    return value === '1' || value === 'true' || value === 'yes';
+}

package/dist/config/peer-role-resolver.js

@@ -0,0 +1,218 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { agentConfig, agentContactConfig, agentRelationsDir } from '../paths.js';
+import { formatPeerKey, parsePeerKey } from '../core/relation/peer-identity.js';
+import { hasTrustedPrincipal } from '../core/auth/authenticated-actor.js';
+import { ConfigTarget, read, write } from './config-manager.js';
+import { isManagementRole } from './builtin-roles.js';
+import { getRoleDefinition, getRoleRank, normalizeDefaultRole, roleExists } from './roles.js';
+import { getStoredRoleRegistry, roleRegistryExists } from './role-store.js';
+import { resolvePrincipal } from './contact-book.js';
+import { isValidAid } from '../aun/aid/validation.js';
+import { isExplicitGroupId } from '../aun/group-identity.js';
+export function isAuthenticated(userId) {
+    return isValidAid(String(userId || '').trim());
+}
+export function listStaticAgentOwners(aid, opts = {}) {
+    return listAgentOwners(aid, opts);
+}
+/** Direct AUN relations with role=admin are the addressable Agent admin set. */
+export function listStaticAgentAdmins(aid, opts = {}) {
+    if (!aid)
+        return [];
+    const relations = agentRelationsDir(aid);
+    if (!fs.existsSync(relations))
+        return [];
+    const admins = new Set();
+    for (const entry of fs.readdirSync(relations, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('_'))
+            continue;
+        let parsed;
+        try {
+            parsed = parsePeerKey(entry.name);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.channelType !== 'aun'
+            || !isValidAid(parsed.channelId)
+            || isExplicitGroupId(parsed.channelId))
+            continue;
+        const config = read(ConfigTarget.Relation, { self: aid, peerKey: entry.name }, { cache: opts.fresh !== true });
+        if (config?.targetKind === 'group')
+            continue;
+        if (config?.role === 'admin')
+            admins.add(parsed.channelId);
+    }
+    return [...admins].sort();
+}
+export function getFirstStaticAgentOwner(aid) {
+    return listStaticAgentOwners(aid)[0];
+}
+/** Revision for security-sensitive owner/contact/relation authorization inputs. */
+export function authorizationConfigRevision(aid) {
+    const fingerprints = [fileRevision(agentConfig(aid)), fileRevision(agentContactConfig(aid))];
+    const relations = agentRelationsDir(aid);
+    try {
+        for (const entry of fs.readdirSync(relations, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory() || entry.name.startsWith('_'))
+                continue;
+            fingerprints.push(entry.name, fileRevision(path.join(relations, entry.name, 'config.json')));
+        }
+    }
+    catch { }
+    return crypto.createHash('sha256').update(JSON.stringify(fingerprints)).digest('hex');
+}
+export function isStaticAgentOwner(aid, actorId) {
+    return !!aid && !!actorId && listStaticAgentOwners(aid).includes(actorId);
+}
+export function isStaticAgentAdmin(aid, actorId) {
+    if (!aid || !isValidAid(actorId) || isExplicitGroupId(actorId))
+        return false;
+    const config = read(ConfigTarget.Relation, { self: aid, peerKey: formatPeerKey('aun', actorId) }, { cache: true });
+    return config?.targetKind !== 'group' && config?.role === 'admin';
+}
+export function addStaticAgentOwner(aid, ownerAid) {
+    if (!aid || !ownerAid)
+        return;
+    const config = read(ConfigTarget.Agent, { self: aid }) ?? { $schema_version: 3, aid, channels: [] };
+    const owners = new Set((config.owners ?? []).filter(Boolean));
+    owners.add(ownerAid);
+    write(ConfigTarget.Agent, { ...config, aid, owners: [...owners] }, { self: aid });
+}
+export function hasStaticAgentOwner(aid) {
+    return listStaticAgentOwners(aid).length > 0;
+}
+export function resolvePeerRoleDetail(ctx) {
+    const operatorId = String(ctx.actorId || '').trim();
+    const channelType = String(ctx.channelType || '').trim().toLowerCase();
+    const channelKey = String(ctx.channelKey || '').trim();
+    const principal = resolvePrincipal(ctx.selfAid, channelType, operatorId, channelKey || undefined);
+    const actor = {
+        operatorId,
+        operatorChannelKey: channelKey || channelType,
+        operatorChannelType: channelType,
+        ...principal,
+    };
+    const candidates = [];
+    if (hasTrustedPrincipal(actor) && isStaticAgentOwner(ctx.selfAid, actor.principalId)) {
+        candidates.push({ role: 'owner', source: 'agent-owner', sourcePriority: 100 });
+    }
+    const actorRole = resolveActorDirectRole(ctx.selfAid, actor, channelType, operatorId);
+    if (ctx.chatType === 'private') {
+        if (actorRole)
+            candidates.push({ role: actorRole, source: 'relation-actor', sourcePriority: 80 });
+        const defaultRole = normalizeDefaultRole(readAgentDefaultRole(ctx.selfAid, 'private'), ctx.selfAid);
+        if (defaultRole)
+            candidates.push({ role: defaultRole, source: 'agent-default', sourcePriority: 40 });
+    }
+    else {
+        if (actorRole)
+            candidates.push({ role: actorRole, source: 'relation-actor', sourcePriority: 80 });
+        const groupRole = normalizeRelationRole(readDirectRelationRole(ctx.selfAid, channelType, String(ctx.conversationId || '').trim(), 'group'), ctx.selfAid);
+        if (groupRole) {
+            candidates.push({ role: groupRole, source: 'relation-peer', sourcePriority: 60 });
+        }
+        else {
+            const defaultRole = normalizeDefaultRole(readAgentDefaultRole(ctx.selfAid, 'group'), ctx.selfAid);
+            if (defaultRole)
+                candidates.push({ role: defaultRole, source: 'agent-default', sourcePriority: 40 });
+        }
+    }
+    const winner = selectHighestRank(candidates, ctx.selfAid);
+    if (winner)
+        return resultFor(winner.role, winner.source, actor, ctx.selfAid);
+    return roleRegistryExists(ctx.selfAid) && roleExists('visitor', ctx.selfAid)
+        ? resultFor('visitor', 'builtin-fallback', actor, ctx.selfAid)
+        : resultFor(null, 'none', actor, ctx.selfAid);
+}
+export function roleToSessionIdentity(role) {
+    return { role: role ?? 'none', mode: 'interactive' };
+}
+export function checkRoleAccess(role, selfAid) {
+    if (!role)
+        return false;
+    if (isManagementRole(role))
+        return true;
+    const definition = getRoleDefinition(role, selfAid);
+    return !!definition && (definition.allowAccess ?? true);
+}
+function selectHighestRank(candidates, selfAid) {
+    let winner = null;
+    for (const candidate of candidates) {
+        if (!normalizeRelationRole(candidate.role, selfAid) && candidate.role !== 'owner')
+            continue;
+        if (!winner) {
+            winner = candidate;
+            continue;
+        }
+        const rank = getRoleRank(candidate.role, selfAid);
+        const winnerRank = getRoleRank(winner.role, selfAid);
+        if (rank > winnerRank || (rank === winnerRank && candidate.sourcePriority > winner.sourcePriority)) {
+            winner = candidate;
+        }
+    }
+    return winner;
+}
+function resolveActorDirectRole(selfAid, actor, channelType, actorId) {
+    const role = hasTrustedPrincipal(actor)
+        ? readDirectRelationRole(selfAid, 'aun', actor.principalId, 'private')
+        : actor.principalStatus === 'unmapped'
+            ? readDirectRelationRole(selfAid, channelType, actorId, 'private')
+            : null;
+    return normalizeRelationRole(role, selfAid);
+}
+function resultFor(role, source, actor, selfAid) {
+    const exists = role ? (isManagementRole(role) || roleExists(role, selfAid)) : false;
+    const roleDef = role ? getRoleDefinition(role, selfAid) : null;
+    return {
+        effectiveRole: exists ? role : null,
+        source: exists ? source : 'none',
+        isAuthenticated: hasTrustedPrincipal(actor),
+        allowAccess: !!(roleDef && (roleDef.allowAccess ?? true)),
+        roleExists: exists,
+        actor,
+    };
+}
+function listAgentOwners(aid, opts = {}) {
+    if (!aid)
+        return [];
+    try {
+        const config = read(ConfigTarget.Agent, { self: aid }, { cache: opts.fresh !== true });
+        return Array.from(new Set((config?.owners ?? []).map(value => String(value || '').trim()).filter(Boolean)));
+    }
+    catch {
+        return [];
+    }
+}
+function readAgentDefaultRole(aid, chatType) {
+    return getStoredRoleRegistry(aid).defaultRoles[chatType] ?? null;
+}
+function readDirectRelationRole(selfAid, channelType, channelId, expectedTargetKind) {
+    if (!selfAid || !channelType || !channelId)
+        return undefined;
+    if (expectedTargetKind === 'private' && channelType === 'aun' && isExplicitGroupId(channelId))
+        return undefined;
+    const peerKey = formatPeerKey(channelType, channelId);
+    const config = read(ConfigTarget.Relation, { self: selfAid, peerKey }, { cache: true });
+    if (expectedTargetKind && config?.targetKind && config.targetKind !== expectedTargetKind)
+        return undefined;
+    return config?.role;
+}
+function normalizeRelationRole(value, selfAid) {
+    if (typeof value !== 'string' || !value || value === 'owner')
+        return null;
+    if (value === 'admin')
+        return getRoleDefinition('admin', selfAid) ? 'admin' : null;
+    return roleExists(value, selfAid) ? value : null;
+}
+function fileRevision(file) {
+    try {
+        const stat = fs.statSync(file);
+        return [stat.size, stat.mtimeMs].join(':');
+    }
+    catch {
+        return 'missing';
+    }
+}